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