일반적인 문제 및 버그 신고

웹 푸시와 관련된 문제가 발생하면 문제를 디버그하거나 도움을 찾기가 어려울 수 있습니다. 이 문서에서는 몇 가지 일반적인 문제와 Chrome 또는 Firefox에서 버그를 발견한 경우 취해야 할 조치를 간략히 설명합니다.

푸시 디버깅을 시작하기 전에 서비스 워커 자체를 디버깅하는 문제, 파일이 업데이트되지 않거나 등록되지 않는 문제 또는 일반적으로 비정상적인 동작이 발생할 수 있습니다. 서비스 워커 개발을 처음 접하는 경우 서비스 워커 디버깅에 관한 유용한 문서를 확인해 보시기 바랍니다.

웹 푸시를 개발하고 테스트할 때 확인해야 하는 두 가지 단계가 있으며 각 단계에는 자체적인 일반적인 문제 / 문제가 있습니다.

  • 메시지 전송: 메시지가 전송되었는지 확인합니다. 201 HTTP 코드가 표시됩니다. 해당되지 않는 경우:
    • 승인 오류 확인: 승인 오류 메시지가 표시되면 승인 문제 섹션을 참고하세요.
    • 기타 API 오류: 201이 아닌 상태 코드 응답이 수신되면 HTTP 상태 코드 섹션에서 문제의 원인에 관한 안내를 참고하세요.
  • 메시지 수신: 메시지를 보낼 수 있지만 브라우저에서 메시지가 수신되지 않는 경우 다음 단계를 따르세요.

푸시 메시지를 주고받을 수 없고 이 문서의 관련 섹션이 문제를 디버그하는 데 도움이 되지 않는다면 푸시 메커니즘 자체에 버그가 있을 수 있습니다. 이 경우 버그 신고 제출 섹션을 참고하여 버그 수정 절차를 신속하게 진행하는 데 필요한 모든 정보가 포함된 양질의 버그 신고를 제출하세요.

시작하기 전에 한 가지 말씀드리고 싶은 점은 Firefox 및 Mozilla AutoPush 서비스에 훌륭한 오류 메시지가 있습니다. 문제가 발생하여 문제가 무엇인지 잘 모르겠다면 Firefox에서 테스트하여 더 유용한 오류 메시지가 표시되는지 확인하세요.

승인 문제

승인 문제는 개발자가 웹 푸시를 시작할 때 가장 자주 겪는 문제 중 하나입니다. 이는 일반적으로 사이트의 애플리케이션 서버 키 (VAPID 키) 구성에 문제가 있는 것입니다.

Firefox와 Chrome에서 모두 푸시를 지원하는 가장 쉬운 방법은 subscribe() 호출에 applicationServerKey를 제공하는 것입니다. 단점은 프런트엔드와 서버의 키가 일치하지 않으면 승인 오류가 발생한다는 점입니다.

Chrome 및 FCM

FCM을 푸시 서비스로 사용하는 Chrome의 경우 애플리케이션 서버 키와 관련된 다양한 오류에 대해 FCM으로부터 UnauthorizedRegistration 응답을 받게 됩니다.

다음과 같은 경우에 UnauthorizedRegistration 오류가 발생합니다.

  • FCM에 대한 요청에서 Authorization 헤더를 정의하지 않으면
  • 사용자를 구독하는 데 사용된 애플리케이션 키가 승인 헤더에 서명하는 데 사용된 키와 일치하지 않습니다.
  • JWT의 만료가 유효하지 않습니다. 즉, 만료 시간이 24시간을 초과하거나 JWT가 만료되었습니다.
  • JWT의 형식이 잘못되었거나 유효하지 않은 값이 있습니다.

전체 오류 응답은 다음과 같습니다.

<html>
  <head>
    <title>UnauthorizedRegistration</title>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <h1>UnauthorizedRegistration</h1>

    <h2>Error 400</h2>
  </body>
</html>

Chrome에서 이 오류 메시지가 표시되면 Firefox에서 테스트하여 문제에 대한 더 많은 정보를 얻을 수 있는지 확인해 보세요.

Firefox 및 Mozilla AutoPush

Firefox 및 Mozilla AutoPush는 Authorization 문제에 관한 친절한 오류 메시지 세트를 제공합니다.

푸시 요청에 Authorization 헤더가 포함되지 않은 경우에도 Mozilla AutoPush에서 Unauthorized 오류 응답을 수신합니다.

{
  "errno": 109,
  "message": "Request did not validate missing authorization header",
  "code": 401,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Unauthorized"
}

JWT의 만료일이 지난 경우 토큰이 만료되었다는 메시지와 함께 Unauthorized 오류도 표시됩니다.

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid bearer token: Auth expired"
}

사용자가 구독된 시점과 승인 헤더가 서명된 시점의 애플리케이션 서버 키가 다른 경우 Not Found 오류가 반환됩니다.

{
  "errno": 102,
  "message": "Request did not validate invalid token",
  "code": 404,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Not Found"
}

마지막으로 JWT에 잘못된 값이 있는 경우 (예: 'alg' 값이 예상치 못한 값인 경우) Mozilla AutoPush에서 다음과 같은 오류가 발생합니다.

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid Authorization Header"
}

HTTP 상태 코드

푸시 서비스에서 201이 아닌 응답 코드가 발생할 수 있는 다양한 문제가 있습니다. 다음은 HTTP 상태 코드 목록과 웹 푸시와 관련된 의미입니다.

상태 코드 설명
429 요청이 너무 많습니다. 애플리케이션 서버가 푸시 서비스의 비율 한도에 도달했습니다. 서비스의 응답에는 다른 요청을 실행할 수 있기까지의 시간을 나타내는 'Retry-After' 헤더가 포함되어야 합니다.
400 요청이 잘못되었습니다. 헤더 중 하나가 잘못되었거나 형식이 잘못되었습니다.
404 찾을 수 없음 이 경우 백엔드에서 PushSubscription을 삭제하고 사용자를 다시 구독할 기회를 기다려야 합니다.
410 사라졌습니다. 구독이 더 이상 유효하지 않으므로 백엔드에서 삭제해야 합니다. 이는 `PushSubscription`에서 `unsubscribe()`를 호출하여 재현할 수 있습니다.
413 페이로드 크기가 너무 큽니다. 푸시 서비스에서 지원해야 하는 최소 페이로드 크기는 4,096바이트 (또는 4KB)입니다. 그보다 큰 경우 이 오류가 발생할 수 있습니다.

HTTP 상태 코드가 이 목록에 없고 오류 메시지가 유용하지 않은 경우 웹 푸시 프로토콜 사양에서 상태 코드가 사용될 수 있는 시나리오와 함께 상태 코드가 참조되는지 확인하세요.

페이로드 암호화 문제

푸시 메시지를 성공적으로 트리거할 수 있지만 (즉, 웹 푸시 서비스에 메시지를 전송하고 201 응답 코드를 수신함) 서비스 워커에서 푸시 이벤트가 실행되지 않는 경우 일반적으로 브라우저가 수신한 메시지를 복호화하지 못했다는 것을 나타냅니다.

이 경우 Firefox의 DevTools 콘솔에 다음과 같은 오류 메시지가 표시됩니다.

복호화 메시지가 있는 Firefox DevTools

Chrome에서 이 문제가 맞는지 확인하려면 다음 단계를 따르세요.

  1. about://gcm-internals로 이동하여 'Start Recording'(녹화 시작) 버튼을 클릭합니다.

Chrome GCM 내부 레코드

  1. 푸시 메시지를 트리거하고 '메시지 복호화 실패 로그'를 확인합니다.

GCM 내부 복호화 로그

페이로드 복호화에 문제가 있는 경우 위에 표시된 것과 유사한 오류가 표시됩니다. 세부정보 열에 AES-GCM decryption failed 메시지가 표시됩니다.

이 문제가 있는 경우 암호화를 디버그하는 데 도움이 되는 몇 가지 도구가 있습니다.

연결 문제

서비스 워커에서 푸시 이벤트를 수신하지 못하고 복호화 오류가 표시되지 않으면 브라우저가 푸시 서비스에 연결하지 못하고 있을 수 있습니다.

Chrome에서는 about://gcm-internals의 '메시지 수신 로그'를 검사하여 브라우저가 메시지를 수신하고 있는지 확인할 수 있습니다.

GCM 내부에서 메시지 로그를 수신합니다.

메시지가 제때 수신되지 않으면 브라우저의 연결 상태가 CONNECTED인지 확인합니다.

GCM 내부 연결 상태입니다.

'연결됨'이 아닌 경우 현재 프로필을 삭제하고 새 프로필을 만들어야 할 수 있습니다. 그래도 문제가 해결되지 않으면 아래의 제안사항에 따라 버그 신고를 제출하세요.

버그 신고 제출

위 방법으로 문제가 해결되지 않고 문제가 무엇인지 알 수 있는 징후가 없는 경우 문제가 발생한 브라우저에 대해 문제를 제기하세요.

Chrome의 경우 여기(https://bugs.chromium.org/p/chromium/issues/list)에서 문제를 제기합니다. Firefox의 경우 여기(https://bugzilla.mozilla.org/)에서 문제를 제기해야 합니다.

적절한 버그 신고를 제공하려면 다음 세부정보를 제공해야 합니다.

  • 테스트한 브라우저 (예: Chrome 버전 50, Chrome 버전 51, Firefox 버전 50, Firefox 버전 51)
  • 문제를 보여주는 예시 PushSubscription
  • 요청 예시 (즉, 헤더를 포함하여 푸시 서비스에 대한 네트워크 요청의 콘텐츠)를 포함합니다.
  • 네트워크 요청의 응답 예시도 포함합니다.

재현 가능한 예시(소스 코드 또는 호스팅된 웹사이트)를 제공할 수 있으면 문제의 진단 및 해결 속도가 빨라지는 경우가 많습니다.

다음에 수행할 작업

Codelab