이 페이지는 Cloud Translation API를 통해 번역되었습니다.

일반적인 문제 및 버그 신고

Matt Gaunt

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

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

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

메시지 보내기: 메시지가 성공적으로 전송되었는지 확인합니다. 201 HTTP 코드가 표시됩니다. 해당하지 않는 경우:
- 승인 오류 확인: 승인 오류 메시지가 표시되면 승인 문제 섹션을 참조하세요.
- 기타 API 오류: 201이 아닌 상태 코드 응답을 받으면 HTTP 상태 코드 섹션에서 문제의 원인에 대한 안내를 참조하세요.
메시지 수신: 메시지를 보낼 수 있지만 브라우저에서 메시지가 수신되지 않는 경우:
- 암호화 문제 확인: 페이로드 암호화 문제 섹션을 참고하세요.
- 연결 문제 확인: Chrome에 문제가 있는 경우 연결 문제일 수 있습니다. 자세한 내용은 연결 문제 섹션을 참고하세요.

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

시작하기 전에 한 가지 말씀드리고 싶은 것은 Firefox와 Mozilla AutoPush Service에는 훌륭한 오류 메시지가 있습니다. 문제가 무엇인지 잘 모르는 경우 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 자동 푸시

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 자동 푸시에서 다음과 같은 오류가 발생합니다.

{
  "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에서 이러한 문제가 발생하는지 확인하려면 다음 단계를 따르세요.

about://gcm-internals로 이동하여 '기록 시작' 버튼을 클릭합니다.

Chrome GCM 내부 레코드

푸시 메시지를 트리거하여 '메일 복호화 실패 로그'를 살펴봅니다.

GCM 내부 복호화 로그

페이로드의 복호화에 문제가 있으면 위에 표시된 것과 유사한 오류가 표시됩니다. (세부정보 열에서 AES-GCM decryption failed 메시지를 확인하세요.)

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

연결 문제

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

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

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

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

GCM 내부 연결 상태입니다.

'CONNECTED'가 아닌 경우 현재 프로필을 삭제하고 새 프로필을 만들어야 할 수 있습니다. 그래도 문제가 해결되지 않으면 아래와 같이 버그 신고를 제출하세요.

버그 신고 우선 제기

위의 방법으로도 문제가 해결되지 않고 어떤 문제가 있는지 알 수 없다면 문제가 있는 브라우저에 관해 문제를 제기하세요.

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

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

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

소스 코드나 호스팅된 웹사이트 중 재현 가능한 예를 제공할 수 있으면 문제를 진단하고 해결하는 속도가 더 빨라지는 경우가 많습니다.