WNS 푸시 알림 문제 해결

2025-04-30

이 항목에서는 타일, 토스트(알림 메시지), 배지 알림에 문제가 발생할 때 수행해야 하는 초기 문제 해결 단계에 대해 설명하며, 여기에는 다양한 알림 방법(로컬, 푸시, 예약된 알림 및 정기 알림)이 포함됩니다.

특정 오류 문제 해결

이 섹션에서는 푸시 알림을 사용하는 동안 발생할 수 있는 몇 가지 일반적인 오류에 대해 설명합니다.

이벤트 로그 확인
푸시 알림은 "200 OK" 응답을 수신하지만 표시되지 않습니다.
푸시 알림은 "200 OK" 이외의 코드를 반환합니다.
푸시 알림 채널을 만들려고 할 때 발생하는 오류

이벤트 로그 확인

타일 또는 토스트 알림 푸시 알림이 예상대로 표시되지 않는 경우 이벤트 로그를 확인하십시오.

알림을 받았지만 표시되지 않는 경우: 이벤트 뷰어를 시작하고 애플리케이션 및 서비스\Microsoft\Windows\Apps에서 Microsoft-Windows-TWinUI/운영 로그를 검사합니다.
알림이 전혀 수신되지 않는 경우: 이벤트 뷰어를 시작하고 애플리케이션 및 서비스\Microsoft\Windows\PushNotifications-Platform에서 작동 로그를 검사합니다.

푸시 알림은 "200 OK" 응답을 수신하지만 표시되지 않습니다.

WNS(Windows 푸시 알림 서비스)가 "200 OK" 응답을 반환하는 경우 클라이언트가 온라인 상태인 경우 클라이언트에 알림을 전달합니다. 클라이언트가 온라인이지만 알림을 표시하지 않는지 확인한 경우 다음 단계를 수행합니다.

원인: 알림 콘텐츠의 XML 오류입니다.

수정: 기본 XML 구문을 점검하고, XML이 완전하며 올바른지 확인하세요. XML 콘텐츠의 몇 가지 일반적인 실패 지점은 다음과 같습니다.
- 대/소문자 구분 태그 이름, 속성 이름 및 속성 값은 모두 대소문자를 구분합니다. XML의 대소문자가 정확한지 확인하십시오.
- 지원되는 각 타일 형식에 대해 바인딩 요소를 제공해야 합니다. 보내는 각 알림에서 지원하는 각 타일 크기에 대해 바인딩 요소를 제공해야 합니다.
- 텍스트 문자열에는 예약된 XML 문자가 포함되어서는 안 됩니다. 예를 들어, <i> 및 </i> 태그를 포함해도 타일 또는 알림 문자열을 기울일 수 없습니다. 리터럴 문자 "<i>"를 표시하려는 경우, 이를 제대로 이스케이프해야 합니다. XML의 이스케이프 문자에 대한 자세한 내용은 XML 문자 엔터티 및 XAML을 참조하세요.
- lang 특성에 제공된 값은 ITEF BCP 47 사양을 준수해야 합니다.
- 푸시 알림을 통해 전송된 XML 문자열은 UTF-8 인코딩을 사용해야 합니다.
- 비어있지 않은 src 특성을 사용하여 XML 페이로드에 이미지 요소를 포함하는 경우 유효한 이미지에 대한 참조를 포함해야 합니다. 그렇지 않으면 알림이 삭제됩니다.
원인: 푸시 알림 API 매개 변수의 부적절한 사용

수정: 자세한 내용은 Windows.Networking.PushNotifications 네임스페이스의 API 설명서를 참조하세요.
원인: 헤더 유형이 알림 콘텐츠와 일치하지 않습니다. XWNS-Type 헤더가 페이로드에 지정된 알림 템플릿에 해당하는 값(타일, 배지 또는 토스트)으로 설정되지 않으면 알림이 표시되지 않습니다. 이 불일치로 인해 클라이언트에 오류가 발생하고 알림이 삭제됩니다.

수정: 앱 서버가 X-WNS-Type 헤더에 올바른 값을 사용하고 있는지 확인해야 하므로, 푸시 알림 서비스 요청 및 응답 헤더 를 참조하십시오.
원인: X-WNS-TTL 헤더에 설정된 TTL(Time to Live) 값이 너무 작습니다.

수정: 값이 몇 초 안에 제공된다는 것을 인식하여 더 큰 TTL 값을 제공합니다.

이전 단계의 항목을 해결한 후에도 알림이 표시되지 않으면, 이 주제의 '로컬 타일 알림이 표시되지 않음' 섹션에서 로컬 알림에 대한 문제 해결 단계를 참조하여 추가적인 제안을 확인하세요.

푸시 알림은 "200 OK" 이외의 코드를 반환합니다.

WNS가 "200 OK"를 반환하지 않으면 알림이 클라이언트에 전달되지 않습니다. 반환 코드가 400 대에 있는 경우, 당신(개발자)은 문제를 해결할 수 있습니다.

비고

여기에 구체적으로 나열되지 않은 오류는 COM 오류 코드(WPN, MBN, P2P, Bluetooth)를 참조하세요.

알림 요청이 "400 잘못된 요청"을 반환합니다.
알림 요청이 "401 권한 없음"을 반환합니다.
알림 요청이 "401 권한 없음"을 반환하고 토큰이 만료됨
알림 요청은 "403 사용할 수 없음"을 반환합니다.
알림 요청이 "404 찾을 수 없음"을 반환합니다.
알림 요청은 "406 허용 안 함"을 반환합니다.
알림 요청이 "410 Gone"을 반환합니다.

알림 요청이 "400 잘못된 요청"을 반환합니다.

원인: 하나 이상의 WNS 헤더 사용이 잘못되었거나 HTTP 요청이 잘못되었습니다.

수정: 푸시 알림 서비스 요청 및 응답 헤더를 참조하여 앱 서버가 설명된 바와 같이 모든 사용자 지정 헤더를 사용하고 있는지 확인합니다.

알림 요청이 "401 권한 없음"을 반환합니다.

원인: 앱 서버는 앱을 등록할 때 사용자에게 제공된 올바른 패키지 SID(패키지 보안 식별자) 및 비밀 키를 사용해야 합니다. 최근에 Windows 스토어 대시보드에서 비밀 키를 변경한 경우 앱 서버도 업데이트해야 합니다.

수정: Windows StoreDashboard를 방문하여 패키지 SID 및 비밀을 확인합니다.

알림 요청이 "401 권한 없음"을 반환하고 토큰이 만료됨

원인: 액세스 토큰의 수명은 유한합니다. 액세스 토큰이 만료된 알림을 보내면 앱 서버의 자격 증명이 유효하지 않으며 알림을 보낼 수 없습니다.

수정: 패키지 SID(패키지 보안 식별자) 및 비밀 키를 사용하여 WNS로 인증하여 WNS에서 새 액세스 토큰을 요청합니다. 자세한 내용은 WNS(Windows 푸시 알림 서비스) 개요를 참조하세요.

알림 요청은 "403 사용할 수 없음"을 반환합니다.

원인: 이 오류는 제공한 액세스 토큰이 해당 채널 URL에 알림을 보내는 데 필요한 자격 증명과 일치하지 않을 때 발생합니다. 앱 서버에 대한 자격 증명을 받으려면 모든 앱을 Windows 스토어에 등록해야 합니다. 각 앱에 대해 Windows 스토어에서 제공하는 자격 증명만 해당 앱에 알림을 보내는 데 사용할 수 있으며 해당 특정 앱에만 사용할 수 있습니다.

수정: 개발자 계정으로 Windows 스토어 대시보드에 로그인합니다. 앱을 선택하고 "고급 기능" -> "클라우드 서비스 설정 관리"를 클릭합니다. 클라우드 서비스 자격 증명과 일치하도록 앱 매니페스트 업데이트에 대한 지침을 읽으려면 "앱 식별"을 선택합니다.

알림 요청이 "404 찾을 수 없음"을 반환합니다.

원인: 이 오류는 일반적으로 채널 URL이 올바르게 구성되지 않음을 의미합니다. WNS에 알림을 보낼 때 채널 URL을 변조하거나 수정해서는 안 됩니다. 채널 URL은 항상 불투명 문자열로 처리되어야 하며, 콘텐츠를 검사하거나 알 필요가 없습니다.

수정: 코드가 하나 이상의 문자를 변경하거나 인코딩을 변경하여 채널 URL을 수정하지 않는지 확인합니다.

알림 요청은 "406 허용 안 함"을 반환합니다.

원인: WNS에는 악의적인 앱이 다른 사용자 및 개발자를 위한 서비스에 부정적인 영향을 미치지 않도록 방지하는 보호 정책이 있습니다. 너무 짧은 기간에 과도한 수의 알림이 있으면 WNS에서 알림을 명시적으로 삭제할 수 있습니다.

수정: 알림 빈도를 검토하여 더 나은 사용자 환경을 생성하도록 줄이거나 최적화할 수 있는지 확인합니다.

알림 요청이 "410 Gone"을 반환합니다.

원인: 채널 URL이 만료되었습니다. 앱이 실행되고 새 채널 URL을 요청할 때까지 추가 알림을 보낼 수 없습니다.

수정: Windows 스토어 앱이 실행될 때마다 채널 URL을 요청해야 합니다. 할당된 채널 URL은 동일하게 유지되지 않습니다. URL이 변경된 경우 클라이언트는 클라우드 서버의 정보를 업데이트해야 합니다.

푸시 알림 채널을 만들려고 할 때 발생하는 오류

알림 채널을 만들면 ERROR_NO_NETWORK 오류가 발생합니다.
알림 채널을 만들면 WPN_E_CLOUD_INCAPABLE 오류가 발생합니다.
알림 채널을 만들면 WPN_E_INVALID_APP 오류가 발생합니다.

비고

여기에 구체적으로 나열되지 않은 오류는 COM 오류 코드(WPN, MBN, P2P, Bluetooth)를 참조하세요.

알림 채널을 만들면 ERROR_NO_NETWORK 오류가 발생합니다.

원인: 알림 채널을 만들려면 WNS에 인터넷 연결이 필요합니다.

해결: 인터넷 연결을 확인합니다.

알림 채널을 만들면 WPN_E_CLOUD_INCAPABLE 오류가 발생합니다.

원인: 앱이 앱 매니페스트(package.appxmanifest)에서 인터넷 기능을 선언하지 않았습니다.

수정: 앱 매니페스트에 인터넷 기능이 선언되어 있는지 확인하십시오. Visual Studio 매니페스트 편집기에서 이 옵션은 기능 탭에서 인터넷(클라이언트)으로 찾을 수 있습니다. 자세한 내용은 기능을 참조하세요.

알림 채널을 만들면 WPN_E_INVALID_APP 오류가 발생합니다.

원인: 앱에서 유효한 패키지 이름을 사용해야 합니다. 아직 받지 못한 경우 "고급 기능"에서 Windows 스토어 포털을 통해 가져올 수 있습니다.

수정: Windows 스토어 앱에 대한 PKSID(패키지 보안 식별자)를 검색하는 방법은 WNS(Windows 푸시 알림 서비스) 개요를 참조하세요.

문제 신고

이 항목에서 제안된 솔루션을 시도했지만 문제를 해결하지 못한 경우 Microsoft 포럼 에 메시지를 게시하여 Microsoft 개발자 및 기타 이해 관계자와 논의합니다.

푸시 알림의 경우 문제에 대한 설명 외에도 HTTP 오류 코드와 HTTP 헤더를 포함하여 채널 URL 및 WNS에서 받은 응답의 예를 제공하라는 메시지가 표시될 수 있습니다. 문제를 보고할 때 앱 서버가 로깅해야 하는 특정 헤더가 있습니다. 자세한 내용은 푸시 알림 서비스 요청 및 응답 헤더을 참조하세요.