일반적인 문제 및 버그 신고

Matt Gaunt

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

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

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

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

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

시작하기 전에 한 가지 말씀드리고 싶은 것은 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 콘솔에 다음과 같은 오류 메시지가 표시됩니다.

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

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

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

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

암호화 문제가 있는 경우 디버깅에 도움이 되는 몇 가지 도구가 있습니다.

• Peter Beverloo의 푸시 암호화 검사기 도구
• 웹 푸시: Mozilla의 데이터 암호화 테스트 페이지

연결 문제

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

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

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

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

버그 신고 제출

위의 방법으로도 문제가 해결되지 않고 문제의 원인을 알 수 없는 경우 문제가 발생한 브라우저에 대해 문제를 제기하세요.

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

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

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

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

다음에 수행할 작업

• 웹 푸시 알림 개요
• 푸시 작동 방식
• 사용자 구독
• 권한 UX
• 웹 푸시 라이브러리를 사용하여 메시지 보내기
• 웹 푸시 프로토콜
• 푸시 이벤트 처리
• 알림 표시
• 알림 동작
• 일반적인 알림 패턴
• 푸시 알림 FAQ
• 일반적인 문제 및 버그 신고

코드 실습

• 푸시 알림 클라이언트 빌드
• 푸시 알림 서버 빌드