웹 푸시와 관련된 문제가 발생하면 문제를 디버그하거나 도움을 찾기가 어려울 수 있습니다. 이 문서에서는 몇 가지 일반적인 문제와 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에서 이 문제가 맞는지 확인하려면 다음 단계를 따르세요.
- about://gcm-internals로 이동하여 'Start Recording'(녹화 시작) 버튼을 클릭합니다.
- 푸시 메시지를 트리거하고 '메시지 복호화 실패 로그'를 확인합니다.
페이로드 복호화에 문제가 있는 경우 위에 표시된 것과 유사한 오류가 표시됩니다. 세부정보 열에 AES-GCM decryption failed
메시지가 표시됩니다.
이 문제가 있는 경우 암호화를 디버그하는 데 도움이 되는 몇 가지 도구가 있습니다.
연결 문제
서비스 워커에서 푸시 이벤트를 수신하지 못하고 복호화 오류가 표시되지 않으면 브라우저가 푸시 서비스에 연결하지 못하고 있을 수 있습니다.
Chrome에서는 about://gcm-internals
의 '메시지 수신 로그'를 검사하여 브라우저가 메시지를 수신하고 있는지 확인할 수 있습니다.
메시지가 제때 수신되지 않으면 브라우저의 연결 상태가 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
- 일반적인 문제 및 버그 신고