이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

푸시 알림 문제 해결

이 페이지를 사용하여 기기에서 푸시 알림 전달 및 표시 문제를 진단하세요. 대시보드 측 전달 점검(구독 상태, Segment, 한도)에 대해서는 푸시 문제 해결을 참조하세요.

디버깅하기 전에 테스트 사용자로 자신을 추가하고 테스트 메시지 발송을 검토하세요.

시작하기: 증상 매칭

아래 표에서 현재 겪고 있는 동작을 찾은 다음 해당 섹션의 단계를 따르세요. 어떤 섹션이 해당되는지 확실하지 않은 경우 표준 조사 경로를 사용하세요.

증상	이동
특정 플랫폼에서 푸시가 수신되지 않음	플랫폼별 문제 해결에서 SDK 탭을 선택하세요
저장 시 Liquid 태그 주변의 줄 바꿈이 이상하게 보임	푸시 알림의 줄 바꿈
대시보드 전달 점검(구독, Segment, 한도)	푸시 문제 해결
푸시에서 딥링크가 올바르게 열리지 않음	딥링킹 문제 해결
일반적인 푸시 오류 코드	일반적인 푸시 오류 메시지

표준 조사 경로

모든 푸시 알림 인시던트에 대해 이 워크플로를 사용하세요. 1단계부터 시작합니다.

기기에 유효한 푸시 토큰이 있고 기기 설정에서 푸시 권한이 부여되어 있는지 확인합니다.
대시보드에서 테스트 사용자가 Campaign 또는 Canvas Segment에 일치하고 대조군에 포함되어 있지 않은지 확인합니다.
테스트 기기로 테스트 푸시를 발송합니다.
상세 로깅을 활성화하고, 문제를 재현한 다음, SDK 탭에서 플랫폼별 가이드를 검토합니다.
문제가 지속되면 상세 로그, 플랫폼, SDK 버전, Campaign 또는 Canvas ID와 함께 Braze 고객지원에 문의하세요.

플랫폼별 문제 해결

플랫폼별 설정 및 표시 점검을 위해 SDK 탭을 선택하세요.

문제 해결

푸시 알림을 설정한 후 문제가 발생하는 경우 다음 사항을 확인하세요:

웹 푸시 알림을 사용하려면 사이트가 HTTPS여야 합니다.
모든 브라우저가 푸시 메시지를 수신할 수 있는 것은 아닙니다. 브라우저에서 braze.isPushSupported()가 true를 반환하는지 확인하세요.
Firefox와 같은 일부 브라우저는 푸시 알림에 이미지를 표시하지 않습니다. 브라우저 지원에 대한 자세한 내용은 MDN Notification 이미지 문서를 참조하세요.
사용자가 사이트의 푸시 액세스를 거부한 경우, 브라우저 환경설정에서 거부 상태를 제거하지 않는 한 권한을 다시 요청하는 메시지가 표시되지 않습니다.

Braze 푸시 워크플로우 이해하기

Firebase 클라우드 메시징(FCM) 서비스는 Android 애플리케이션으로 전송되는 푸시 알림을 위한 Google의 인프라입니다. 다음은 사용자의 기기에서 푸시 알림을 활성화하는 방법과 Braze가 푸시 알림을 보내는 방법에 대한 간단한 구조입니다:

---
config:
  theme: mc
---
sequenceDiagram
  participant Device as User Device
  participant App as Android App
  participant BrazeSDK as Braze SDK
  participant BrazeAPI as Braze Server
  participant Firebase as Google Firebase
  Note over Device, Firebase: Register Option 1<br/>Register Automatically using `com_braze_firebase_cloud_messaging_registration_enabled` in braze.xml
  App ->> Braze: App initializes Braze with the first Braze call<br>This could be automatic session handling
  BrazeSDK ->> App: Get push token from Firebase Manager
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Register Option 2<br/>Manual registration.
  App ->> BrazeSDK: App sets `Braze.registeredPushToken`
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Push permission
  BrazeAPI ->> BrazeSDK: In-App Message containing push prompt
  BrazeSDK -> App: In-App Message is displayed
  App -> BrazeSDK: User requests permissions
  BrazeSDK -> App: Displays the Push Authorization prompt
  BrazeSDK -> BrazeAPI: If authorized and `com_braze_optin_when_push_authorized`, Opt-In value is sent.
  Note over Device, Firebase: Push Notification Is Sent
  BrazeAPI ->> Firebase: Sends push message
  Firebase ->> Device: Push message sent
  Device ->> App: Android will send the push to the App.<br>This could be blocked to Do Not Disturb, Power Saving Mode, etc.
  App ->> BrazeSDK: Message is sent to BrazeFirebaseMessagingService
  BrazeSDK ->> Device: SDK will check if the push is from Braze.<br>If so, push data is transformed into a Push Notification and displayed.

1단계: Google Cloud API 키 구성

앱을 개발할 때 Braze Android SDK에 Firebase 발신자 ID를 제공해야 합니다. 또한 서버 애플리케이션용 API 키를 Braze 대시보드에 제공해야 합니다. Braze는 이 API 키를 사용하여 사용자 기기로 메시지를 전송합니다. Google 개발자 콘솔에서 FCM 서비스가 활성화되어 있는지도 확인해야 합니다.

참고

이 단계에서 흔히 하는 실수는 REST API 키 대신 앱 식별자 API 키를 사용하는 것입니다.

2단계: 기기가 FCM에 등록하고 Braze에 푸시 토큰을 제공

일반적인 통합에서는 Braze Android SDK가 FCM 기능을 위한 기기 등록을 처리합니다. 보통 앱을 처음 열면 바로 이 과정이 진행됩니다. 등록 후 Braze에 FCM 등록 ID가 제공되며, 이 ID를 사용하여 해당 기기로만 메시지를 전송합니다. 해당 사용자의 등록 ID가 저장되며, 이전에 앱에 대한 푸시 토큰이 없었던 경우 해당 사용자는 “푸시 등록” 상태가 됩니다.

3단계: Braze 푸시 Campaign 시작

푸시 Campaign이 시작되면 Braze는 FCM에 메시지 전달을 요청합니다. Braze는 대시보드에 복사된 API 키를 사용하여 인증하고 제공된 푸시 토큰으로 푸시 알림을 보낼 수 있는지 확인합니다.

4단계: 유효하지 않은 토큰 제거

FCM에서 메시지를 보내려고 했던 푸시 토큰이 유효하지 않다고 알려주면, 해당 토큰이 연결된 고객 프로필에서 해당 토큰을 제거합니다. 사용자에게 다른 푸시 토큰이 없는 경우, Segments 페이지에서 더 이상 “푸시 등록됨”으로 표시되지 않습니다.

FCM에 대한 자세한 내용은 클라우드 메시징을 참조하세요.

푸시 오류 로그 활용하기

Braze는 메시지 활동 로그 내에서 푸시 알림 오류를 제공합니다. 이 오류 로그는 Campaign이 예상대로 작동하지 않는 이유를 파악하는 데 매우 유용한 다양한 경고를 제공합니다. 오류 메시지를 선택하면 특정 인시던트 문제를 해결하는 데 도움이 되는 관련 설명서로 리디렉션됩니다.

푸시 알림 오류 항목이 표시된 Braze 메시지 활동 로그

문제 해결

푸시가 전송되지 않음

다음과 같은 상황으로 인해 푸시 메시지가 전송되지 않을 수 있습니다:

자격 증명이 잘못된 Google Cloud Platform 프로젝트 ID(잘못된 발신자 ID)에 있습니다.
자격 증명의 권한 범위가 잘못되었습니다.
잘못된 Braze 워크스페이스에 잘못된 자격 증명을 업로드했습니다(잘못된 발신자 ID).

푸시 메시지 전송을 방해할 수 있는 기타 문제에 대해서는 사용자 가이드: 푸시 알림 문제 해결을 참조하세요.

Braze 대시보드에 “푸시 등록” 사용자가 표시되지 않음(메시지 전송 전)

앱이 푸시 알림을 허용하도록 올바르게 구성되었는지 확인합니다. 확인해야 할 일반적인 실패 지점은 다음과 같습니다:

잘못된 발신자 ID

braze.xml 파일에 올바른 FCM 발신자 ID가 포함되어 있는지 확인합니다. 발신자 ID가 잘못되면 대시보드의 메시지 활동 로그에 MismatchSenderID 오류가 보고됩니다.

Braze 등록이 발생하지 않음

FCM 등록은 Braze 외부에서 처리되므로 등록 실패는 두 경우에서만 발생할 수 있습니다:

FCM에 등록하는 동안
FCM에서 생성된 푸시 토큰을 Braze에 전달할 때

중단점을 설정하거나 로깅을 통해 FCM에서 생성된 푸시 토큰이 Braze로 전송되는지 확인하는 것이 좋습니다. 토큰이 올바르게 생성되지 않거나 전혀 생성되지 않는 경우 FCM 설명서를 참조하시기 바랍니다.

Google Play 서비스 없음

FCM 푸시가 작동하려면 기기에 Google Play 서비스가 있어야 합니다. 기기에 Google Play 서비스가 설치되어 있지 않은 경우 푸시 등록이 이루어지지 않습니다.

참고

Google API가 설치되지 않은 Android 에뮬레이터에는 Google Play 서비스가 설치되지 않습니다.

기기가 인터넷에 연결되지 않음

기기의 인터넷 연결 상태가 양호하고 프록시를 통해 네트워크 트래픽을 전송하고 있지 않은지 확인하세요.

푸시 알림을 탭해도 앱이 열리지 않음

com_braze_handle_push_deep_links_automatically가 true 또는 false로 설정되어 있는지 확인합니다. 푸시 알림을 탭할 때 Braze가 앱과 딥링크를 자동으로 열도록 설정하려면 braze.xml 파일에서 com_braze_handle_push_deep_links_automatically를 true로 설정합니다.

com_braze_handle_push_deep_links_automatically가 기본값인 false로 설정된 경우, Braze 푸시 콜백을 사용하여 푸시 수신 및 열람 인텐트를 수신 대기하고 처리해야 합니다.

푸시 알림 반송

푸시 알림이 전달되지 않으면 개발자 콘솔에서 반송되지 않았는지 확인합니다. 다음은 개발자 콘솔에 기록될 수 있는 일반적인 오류에 대한 설명입니다:

오류: MismatchSenderID

MismatchSenderID는 인증 실패를 나타냅니다. Firebase 발신자 ID와 FCM API 키가 올바른지 확인합니다.

오류: InvalidRegistration

InvalidRegistration은 잘못된 푸시 토큰으로 인해 발생할 수 있습니다.

Firebase 클라우드 메시징에서 유효한 푸시 토큰을 Braze에 전달해야 합니다.

오류: NotRegistered

NotRegistered는 여러 번의 등록이 발생하고 두 번째 등록이 첫 번째 토큰을 무효화할 때도 발생할 수 있습니다.

푸시 알림이 전송되었지만 사용자의 기기에 표시되지 않음

이러한 문제가 발생하는 데에는 몇 가지 이유가 있습니다:

애플리케이션이 강제 종료됨

시스템 설정을 통해 애플리케이션을 강제 종료하면 푸시 알림이 전송되지 않습니다. 앱을 다시 실행하면 기기에서 푸시 알림을 다시 받을 수 있습니다.

BrazeFirebaseMessagingService가 등록되지 않음

푸시 알림이 표시되려면 BrazeFirebaseMessagingService가 AndroidManifest.xml에 올바르게 등록되어 있어야 합니다:

<service android:name="com.braze.push.BrazeFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

방화벽이 푸시를 차단하고 있음

Wi-Fi를 통해 푸시를 테스트하는 경우 방화벽이 FCM이 메시지를 수신하는 데 필요한 포트를 차단할 수 있습니다. 5228, 5229, 5230 포트가 열려 있는지 확인합니다. 또한 FCM은 IP를 지정하지 않으므로 방화벽이 Google의 ASN(15169)에 나열된 IP 블록에 포함된 모든 IP 주소로 나가는 연결을 수락하도록 허용해야 합니다.

커스텀 알림 팩토리에서 null 반환

커스텀 알림 팩토리를 구현한 경우 null을 반환하지 않는지 확인하세요. null을 반환하면 알림이 표시되지 않습니다.

메시지 전송 후 “푸시 등록” 사용자가 더 이상 활성화되지 않음

이런 일이 발생하는 데에는 몇 가지 이유가 있습니다:

애플리케이션이 제거됨

사용자가 애플리케이션을 제거했습니다. 이렇게 하면 FCM 푸시 토큰이 무효화됩니다.

잘못된 Firebase 클라우드 메시징 서버 키

Braze 대시보드에 제공된 Firebase 클라우드 메시징 서버 키가 유효하지 않습니다. 제공된 발신자 ID는 앱의 braze.xml 파일에 참조된 발신자 ID와 일치해야 합니다. 서버 키와 발신자 ID는 Firebase 콘솔에서 찾을 수 있습니다:

Firebase 플랫폼의 "설정"과 "클라우드 메시징" 아래에 서버 ID와 서버 키가 표시됩니다.

푸시 클릭이 기록되지 않음

푸시 클릭이 기록되지 않는다면 푸시 클릭 데이터가 아직 서버로 플러시되지 않았을 가능성이 있습니다. Braze Android SDK는 플러시를 조절할 수 있습니다.

커스텀 푸시 핸들러를 구현한 경우, 네이티브 푸시 분석을 올바르게 보존하고 있는지 확인하세요.

푸시 클릭 기록은 네트워크 작업이며 네트워크 제한의 영향을 받습니다. 따라서 Braze Android SDK는 네트워크 장애를 수용하고 실패한 요청을 재시도하지만, 일부 이벤트 손실이 발생할 수 있습니다.

딥링크가 작동하지 않음

딥링크 구성 확인

딥링크는 ADB로 테스트할 수 있습니다. 다음 명령어로 딥링크를 테스트하는 것이 좋습니다:

adb shell am start -W -a android.intent.action.VIEW -d "THE_DEEP_LINK" THE_PACKAGE_NAME

딥링크가 작동하지 않으면 딥링크가 잘못 구성된 것일 수 있습니다. 잘못 구성된 딥링크는 Braze 푸시를 통해 전송할 때 작동하지 않습니다.

커스텀 처리 로직 확인

딥링크가 ADB에서는 올바르게 작동하지만 Braze 푸시에서는 작동하지 않는 경우, 커스텀 푸시 오픈 처리가 구현되어 있는지 확인하세요. 구현되어 있다면 커스텀 처리 코드가 수신 딥링크를 올바르게 처리하는지 확인합니다.

백 스택 동작 비활성화

딥링크가 ADB에서는 올바르게 작동하지만 Braze 푸시에서는 작동하지 않는 경우 백 스택을 비활성화해 보세요. 이렇게 하려면 braze.xml 파일을 업데이트합니다:

<bool name="com_braze_push_deep_link_back_stack_activity_enabled">false</bool>

Braze/APNs 워크플로 이해하기

Apple 푸시 알림 서비스(APNs)는 Apple 플랫폼에서 실행되는 애플리케이션에 푸시 알림을 전송하기 위한 인프라입니다. 다음은 사용자의 기기에서 푸시 알림이 활성화되는 방식과 Braze가 푸시 알림을 전송하는 방식의 간략한 구조입니다:

푸시 인증서 및 프로비저닝 프로필을 구성합니다
기기가 APN에 등록하고 Braze에 푸시 토큰을 제공합니다
Braze 푸시 Campaign을 시작합니다
Braze가 유효하지 않은 토큰을 제거합니다

1단계: 푸시 인증서 및 프로비저닝 프로필 구성

앱을 개발하려면 푸시 알림을 활성화하기 위한 SSL 인증서를 생성해야 합니다. 이 인증서는 앱이 빌드되는 프로비저닝 프로필에 포함되며, Braze 대시보드에도 업로드해야 합니다. 이 인증서를 통해 Braze는 APNs에 사용자를 대신하여 푸시 알림을 전송할 권한이 있음을 알릴 수 있습니다.

프로비저닝 프로필과 인증서에는 개발용과 배포용 두 가지 유형이 있습니다. 혼동을 피하기 위해 배포용 프로필과 인증서만 사용하는 것을 권장합니다. 개발용과 배포용으로 서로 다른 프로필과 인증서를 사용하는 경우, 대시보드에 업로드된 인증서가 현재 사용 중인 프로비저닝 프로필과 일치하는지 확인하세요.

경고

푸시 인증서 환경(개발 대 프로덕션)을 변경하지 마세요. 푸시 인증서를 잘못된 환경으로 변경하면 사용자의 푸시 토큰이 실수로 제거되어 푸시로 도달할 수 없게 될 수 있습니다.

2단계: 기기가 APNs에 등록하고 Braze에 푸시 토큰 제공

사용자가 앱을 열면 푸시 알림 수락 여부를 묻는 메시지가 표시됩니다. 이 메시지를 수락하면 APNs가 해당 기기에 대한 푸시 토큰을 생성합니다. Swift SDK는 기본 자동 플러시 정책을 사용하는 앱에 대해 즉시 비동기적으로 푸시 토큰을 전송합니다. 사용자와 연결된 푸시 토큰이 확보되면, 해당 사용자는 대시보드의 고객 프로필 참여 탭에서 “푸시 등록됨”으로 표시되며, Braze Campaigns에서 푸시 알림을 받을 수 있게 됩니다.

참고

macOS 13부터 특정 기기에서 Xcode 14에서 실행되는 iOS 16 시뮬레이터에서 푸시 알림을 테스트할 수 있습니다. 자세한 내용은 Xcode 14 릴리스 노트를 참조하세요.

푸시 토큰 생성 시 고려 사항

사용자가 다른 기기에 앱을 설치하면, Braze는 동일한 방식으로 다른 토큰을 생성하고 캡처합니다.
사용자가 앱을 재설치하면, SDK가 새 토큰을 생성하여 Braze에 전달합니다. 그러나 APNs와 Braze는 여전히 원래 토큰을 유효한 것으로 기록할 수 있습니다.
사용자가 앱을 삭제하면, Braze는 즉시 알림을 받지 못하며, APNs가 해당 토큰을 폐기할 때까지 토큰은 여전히 유효한 것으로 표시됩니다.
특정 시점에 APNs가 오래된 토큰을 폐기합니다. Braze는 이 과정을 제어하거나 확인할 수 없습니다.

3단계: Braze 푸시 Campaign 시작

푸시 Campaign이 시작되면, Braze는 APNs에 메시지 전달을 요청합니다. 구체적으로, 사용자의 가장 최근 기기로 전송이 선택되지 않은 경우 현재 유효한 각 푸시 토큰에 대해 APNs에 요청이 전달됩니다. Braze가 APNs로부터 성공 응답을 받으면 고객 프로필에 성공적인 전달을 기록하지만, 다음과 같은 이유로 사용자가 실제 메시지를 받지 못할 수 있습니다:

기기의 전원이 꺼져 있는 경우.
기기가 인터넷(Wi-Fi 또는 셀룰러)에 연결되어 있지 않은 경우.
최근에 앱을 삭제한 경우.

Braze는 대시보드에 업로드된 SSL 푸시 인증서를 사용하여 인증하고, 제공된 푸시 토큰에 푸시 알림을 전송할 권한이 있는지 확인합니다. 기기가 온라인 상태이면 Campaign이 전송된 직후 알림이 수신됩니다. Braze는 알림의 기본 APNs 만료 날짜를 30일로 설정합니다.

4단계: 유효하지 않은 토큰 제거

메시지를 전송하려고 시도한 푸시 토큰 중 유효하지 않은 토큰이 있다고 APNs가 알려주면, 해당 토큰과 연결된 고객 프로필에서 해당 토큰을 제거합니다.

참고

토큰이 등록 해제되더라도 APNs가 처음에는 성공 상태를 반환하는 것은 정상적인 동작입니다. APNs는 토큰 무효화 이벤트를 즉시 보고하지 않기 때문입니다. APNs는 사용자 개인정보를 보호하고 앱 삭제 추적을 방지하기 위해 설계된 무작위 일정에 따라 유효하지 않은 토큰에 대한 410 상태 반환을 의도적으로 지연합니다. APNs가 410 상태를 반환할 때까지 등록 해제된 토큰에 알림을 계속 전송해도 안전합니다.

푸시 오류 로그 사용하기

메시지 활동 로그를 사용하면 푸시 알림 오류를 포함하여 Campaigns 및 발송과 관련된 모든 메시지(특히 오류 메시지)를 확인할 수 있습니다. 이 오류 로그는 Campaigns가 예상대로 작동하지 않는 이유를 파악하는 데 매우 유용한 다양한 경고를 제공합니다. 오류 메시지를 선택하면 특정 인시던트를 해결하는 데 도움이 되는 관련 설명서로 리디렉션됩니다.

오류 발생 시간, 앱 이름, 채널, 오류 유형 및 오류 메시지를 표시하는 푸시 오류 로그.

여기에서 볼 수 있는 일반적인 오류에는 “Received Unregistered Sending to Push Token”과 같은 사용자별 알림이 포함됩니다.

또한 Braze는 고객 프로필의 참여 탭에서 푸시 체인지로그도 제공합니다. 이 체인지로그는 토큰 무효화, 푸시 등록 오류, 토큰이 새 사용자로 이동되는 경우 등 푸시 등록 동작에 대한 인사이트를 제공합니다.

푸시 등록 체인지로그를 보여주는 Braze 고객 프로필 참여 탭.

메시지 활동 로그 오류

등록되지 않은 푸시 토큰으로 발송 수신됨

AppDelegate.braze?.notifications.register(deviceToken:) 메서드에서 Braze로 전송되는 푸시 토큰이 유효한지 확인하세요. 메시지 활동 로그에서 푸시 토큰을 확인할 수 있습니다. 6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6과 같이 문자와 숫자가 혼합된 긴 문자열이어야 합니다. 푸시 토큰이 다르게 보이는 경우, Braze에 푸시 토큰을 전송하는 코드를 확인하세요.
푸시 프로비저닝 프로필이 테스트 중인 환경과 일치하는지 확인하세요. 유니버설 인증서는 Braze 대시보드에서 개발 또는 프로덕션 APNs 환경으로 발송하도록 구성할 수 있습니다. 프로덕션 앱에 개발 인증서를 사용하거나 개발 앱에 프로덕션 인증서를 사용하면 작동하지 않습니다.
Braze에 업로드한 푸시 토큰이 푸시 토큰을 전송한 앱을 빌드하는 데 사용한 프로비저닝 프로필과 일치하는지 확인하세요.

토픽에 해당하지 않는 기기 토큰

APNs는 푸시 토큰이 자격 증명에 구성된 토픽(번들 ID)과 일치하지 않을 때 DeviceTokenNotForTopic(HTTP 상태 400)을 반환합니다. Braze는 이를 메시지 활동 로그 또는 푸시 전달 로그에서 DeviceTokenNotForTopic으로 표시할 수 있습니다.

불일치를 해결하려면:

앱의 번들 ID가 Braze의 앱 번들 ID와 일치하는지 확인합니다(설정 > 앱 설정 > 푸시 알림 설정).
앱을 빌드하는 데 사용한 프로비저닝 프로필에 해당 번들 ID에 대한 푸시 기능이 포함되어 있는지 확인합니다.
Braze에 업로드한 푸시 자격 증명이 앱의 환경(개발 대 프로덕션)과 일치하는지 확인합니다.
.p8 키의 경우, Braze의 Team ID와 Key ID가 Apple Developer 계정과 일치하는지 확인합니다.
자격 증명이 교체되었거나 취소된 경우 유효한 .p8 키 또는 .p12 인증서를 다시 업로드합니다.

가능하면 .p8 인증 키를 사용하는 것이 좋습니다. 자격 증명 유형 및 대시보드 상태 표시기에 대해서는 .p8 인증 키로 마이그레이션을 참조하세요.

푸시 토큰으로 발송 시 BadDeviceToken

BadDeviceToken은 APNs 오류 코드이며 Braze에서 발생하는 것이 아닙니다. 이 응답이 반환되는 데에는 다음을 포함하여 여러 가지 이유가 있을 수 있습니다:

앱이 대시보드에 업로드된 자격 증명에 대해 유효하지 않은 푸시 토큰을 수신했습니다.
이 워크스페이스에서 푸시가 비활성화되었습니다.
사용자가 푸시 수신을 거부했습니다.
앱이 제거되었습니다.
Apple이 푸시 토큰을 갱신하여 이전 토큰이 무효화되었습니다.
앱이 프로덕션 환경용으로 빌드되었지만, Braze에 업로드된 푸시 자격 증명이 개발 환경용으로 설정되어 있습니다(또는 그 반대의 경우).

푸시 등록 문제

푸시 등록 프롬프트가 표시되지 않음

앱에서 푸시 알림 등록 프롬프트가 표시되지 않는 경우, 푸시 등록 통합에 문제가 있을 가능성이 높습니다. 설명서를 참고하여 푸시 등록을 올바르게 통합했는지 확인하세요. 또한 코드에 브레이크포인트를 설정하여 푸시 등록 코드가 실행되고 있는지 확인할 수 있습니다.

대시보드에 “푸시 등록” 사용자가 표시되지 않음(메시지 발송 전)

앱이 푸시 알림을 허용하도록 올바르게 구성되어 있는지 확인하세요. 확인해야 할 일반적인 실패 지점은 다음과 같습니다:

앱에서 푸시 알림 허용 프롬프트가 표시되는지 확인하세요. 일반적으로 이 프롬프트는 앱을 처음 열 때 나타나지만, 다른 위치에 표시되도록 프로그래밍할 수도 있습니다. 표시되어야 할 위치에 나타나지 않는 경우, 앱의 기본 푸시 기능 구성에 문제가 있을 가능성이 높습니다.
- 푸시 통합 단계가 성공적으로 완료되었는지 확인하세요.
- 앱이 빌드된 프로비저닝 프로필에 푸시 권한이 포함되어 있는지 확인하세요. Apple 개발자 계정에서 사용 가능한 모든 프로비저닝 프로필을 가져오고 있는지 확인하세요. 이를 확인하려면 다음 단계를 수행하세요:
  1. Xcode에서 Preferences > Accounts로 이동합니다(또는 키보드 단축키 Command+,를 사용합니다).
  2. 개발자 계정에 사용하는 Apple ID를 선택하고 View Details를 클릭합니다.
  3. 다음 페이지에서 Refresh를 클릭하고 사용 가능한 모든 프로비저닝 프로필을 가져오고 있는지 확인합니다.
앱에서 푸시 기능이 올바르게 활성화되어 있는지 확인하세요.
푸시 프로비저닝 프로필이 테스트 중인 환경과 일치하는지 확인하세요. 유니버설 인증서는 Braze 대시보드에서 개발 또는 프로덕션 APNs 환경으로 발송하도록 구성할 수 있습니다. 프로덕션 앱에 개발 인증서를 사용하거나 개발 앱에 프로덕션 인증서를 사용하면 작동하지 않습니다.
코드에 브레이크포인트를 설정하여 registerPushToken 메서드를 호출하고 있는지 확인하세요.
기기를 사용하여 테스트하고 있는지(푸시는 시뮬레이터에서 작동하지 않습니다) 네트워크 연결 상태가 양호한지 확인하세요.

푸시 알림이 발송되었지만 사용자 기기에 표시되지 않음

“푸시 등록” 사용자가 메시지 발송 후 더 이상 활성화되지 않음

이는 사용자의 푸시 토큰이 유효하지 않음을 나타낼 가능성이 높습니다. 이는 여러 가지 이유로 발생할 수 있습니다:

대시보드와 앱 인증서 불일치

대시보드에 업로드한 푸시 인증서가 앱을 빌드할 때 사용한 프로비저닝 프로필의 인증서와 동일하지 않으면, APNs가 토큰을 거부합니다. 올바른 인증서를 업로드했는지 확인하고, 다른 테스트 알림을 시도하기 전에 앱에서 세션을 한 번 더 완료하세요.

앱이 제거됨

사용자가 앱을 제거한 경우, 해당 사용자의 푸시 토큰은 유효하지 않게 되며 다음 발송 시 제거됩니다.

프로비저닝 프로필 재생성

최후의 수단으로, 처음부터 다시 시작하여 완전히 새로운 프로비저닝 프로필을 생성하면 여러 환경, 프로필 및 앱을 동시에 작업할 때 발생하는 구성 오류를 해결할 수 있습니다. 푸시 알림 설정에는 많은 “움직이는 부분”이 있으므로, 때로는 처음부터 다시 시도하는 것이 가장 좋습니다. 이렇게 하면 문제 해결을 계속해야 하는 경우 문제를 격리하는 데에도 도움이 됩니다.

“푸시 등록” 사용자에게 메시지가 전달되지 않음

앱이 포그라운드 상태임

UserNotifications 프레임워크를 통해 푸시를 통합하지 않은 iOS 버전에서는, 푸시 메시지가 수신될 때 앱이 포그라운드에 있으면 메시지가 표시되지 않습니다. 테스트 메시지를 발송하기 전에 테스트 기기에서 앱을 백그라운드로 전환해야 합니다.

테스트 알림 스케줄이 잘못 설정됨

테스트 메시지에 설정한 스케줄을 확인하세요. 현지 시간대 전달 또는 Intelligent Timing으로 설정된 경우, 아직 메시지를 수신하지 못했을 수 있습니다(또는 수신 시 앱이 포그라운드 상태였을 수 있습니다).

테스트 중인 앱에 대해 사용자가 “푸시 등록”되지 않음

테스트 메시지를 보내려는 사용자의 고객 프로필을 확인하세요. 참여 탭에 “푸시 가능한 앱” 목록이 있어야 합니다. 테스트 메시지를 보내려는 앱이 이 목록에 있는지 확인하세요. 사용자는 워크스페이스 내 어떤 앱에 대해서든 푸시 토큰이 있으면 “푸시 등록됨”으로 표시되므로, 이는 일종의 거짓 양성일 수 있습니다.

다음은 푸시 등록에 문제가 있거나, 푸시 발송 후 APNs에 의해 사용자의 토큰이 유효하지 않은 것으로 Braze에 반환되었음을 나타냅니다:

사용자의 연락처 설정을 표시하는 고객 프로필. 푸시 항목에 "앱 없음"이 표시되어 있습니다.

푸시 클릭이 기록되지 않음

푸시 통합 단계를 따랐는지 확인하세요.
Braze는 포그라운드에서 자동으로 수신된 푸시 알림을 처리하지 않습니다(UserNotifications 프레임워크 이전의 기본 포그라운드 푸시 동작). 이는 링크가 열리지 않고 푸시 클릭이 기록되지 않음을 의미합니다. 앱이 아직 UserNotifications 프레임워크를 통합하지 않은 경우, 애플리케이션 상태가 UIApplicationStateActive일 때 Braze는 푸시 알림을 처리하지 않습니다. 앱이 푸시 처리 메서드 호출을 지연하지 않는지 확인하세요. 그렇지 않으면 Swift SDK가 푸시 알림을 자동 포그라운드 푸시 이벤트로 처리하고 핸들링하지 않을 수 있습니다.

딥링크가 작동하지 않는 경우

모든 채널(유니버설 링크, 커스텀 스킴, 이메일, Branch와 같은 서드파티 제공업체 포함)에 대한 종합적인 문제 해결은 딥링킹 문제 해결을 참조하세요.

푸시 클릭 시 웹 링크가 열리지 않는 경우

푸시 알림의 링크가 웹 뷰에서 열리려면 ATS를 준수해야 합니다. 웹 링크가 HTTPS를 사용하는지 확인하세요. 자세한 내용은 ATS 준수를 참조하세요.

푸시 클릭 시 딥링크가 열리지 않는 경우

딥링크를 처리하는 대부분의 코드는 푸시 열람도 함께 처리합니다. 먼저 푸시 열람이 기록되고 있는지 확인하세요. 기록되지 않는 경우 해당 문제를 먼저 해결하세요(이 문제를 해결하면 링크 처리 문제도 함께 해결되는 경우가 많습니다).

열람이 기록되고 있다면, 딥링크 자체의 문제인지 아니면 딥링킹 푸시 클릭 처리의 문제인지 확인하세요. 이를 확인하려면 인앱 메시지 클릭에서 딥링크가 작동하는지 테스트해 보세요.

Braze 푸시 워크플로우 이해하기

---
config:
  theme: mc
---
sequenceDiagram
  participant Device as User Device
  participant App as Android App
  participant BrazeSDK as Braze SDK
  participant BrazeAPI as Braze Server
  participant Firebase as Google Firebase
  Note over Device, Firebase: Register Option 1<br/>Register Automatically using `com_braze_firebase_cloud_messaging_registration_enabled` in braze.xml
  App ->> Braze: App initializes Braze with the first Braze call<br>This could be automatic session handling
  BrazeSDK ->> App: Get push token from Firebase Manager
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Register Option 2<br/>Manual registration.
  App ->> BrazeSDK: App sets `Braze.registeredPushToken`
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Push permission
  BrazeAPI ->> BrazeSDK: In-App Message containing push prompt
  BrazeSDK -> App: In-App Message is displayed
  App -> BrazeSDK: User requests permissions
  BrazeSDK -> App: Displays the Push Authorization prompt
  BrazeSDK -> BrazeAPI: If authorized and `com_braze_optin_when_push_authorized`, Opt-In value is sent.
  Note over Device, Firebase: Push Notification Is Sent
  BrazeAPI ->> Firebase: Sends push message
  Firebase ->> Device: Push message sent
  Device ->> App: Android will send the push to the App.<br>This could be blocked to Do Not Disturb, Power Saving Mode, etc.
  App ->> BrazeSDK: Message is sent to BrazeFirebaseMessagingService
  BrazeSDK ->> Device: SDK will check if the push is from Braze.<br>If so, push data is transformed into a Push Notification and displayed.

1단계: Google Cloud API 키 구성

참고

이 단계에서 흔히 하는 실수는 REST API 키 대신 앱 식별자 API 키를 사용하는 것입니다.

2단계: 기기가 FCM에 등록하고 Braze에 푸시 토큰을 제공

3단계: Braze 푸시 Campaign 시작

4단계: 유효하지 않은 토큰 제거

FCM에 대한 자세한 내용은 클라우드 메시징을 참조하세요.

푸시 오류 로그 활용하기

푸시 알림 오류 항목이 표시된 Braze 메시지 활동 로그

문제 해결

푸시가 전송되지 않음

다음과 같은 상황으로 인해 푸시 메시지가 전송되지 않을 수 있습니다:

자격 증명이 잘못된 Google Cloud Platform 프로젝트 ID(잘못된 발신자 ID)에 있습니다.
자격 증명의 권한 범위가 잘못되었습니다.
잘못된 Braze 워크스페이스에 잘못된 자격 증명을 업로드했습니다(잘못된 발신자 ID).

푸시 메시지 전송을 방해할 수 있는 기타 문제에 대해서는 사용자 가이드: 푸시 알림 문제 해결을 참조하세요.

Braze 대시보드에 “푸시 등록” 사용자가 표시되지 않음(메시지 전송 전)

앱이 푸시 알림을 허용하도록 올바르게 구성되었는지 확인합니다. 확인해야 할 일반적인 실패 지점은 다음과 같습니다:

잘못된 발신자 ID

Braze 등록이 발생하지 않음

FCM 등록은 Braze 외부에서 처리되므로 등록 실패는 두 경우에서만 발생할 수 있습니다:

FCM에 등록하는 동안
FCM에서 생성된 푸시 토큰을 Braze에 전달할 때

Google Play 서비스 없음

참고

Google API가 설치되지 않은 Android 에뮬레이터에는 Google Play 서비스가 설치되지 않습니다.

기기가 인터넷에 연결되지 않음

기기의 인터넷 연결 상태가 양호하고 프록시를 통해 네트워크 트래픽을 전송하고 있지 않은지 확인하세요.

푸시 알림을 탭해도 앱이 열리지 않음

푸시 알림 반송

오류: MismatchSenderID

MismatchSenderID는 인증 실패를 나타냅니다. Firebase 발신자 ID와 FCM API 키가 올바른지 확인합니다.

오류: InvalidRegistration

InvalidRegistration은 잘못된 푸시 토큰으로 인해 발생할 수 있습니다.

Firebase 클라우드 메시징에서 유효한 푸시 토큰을 Braze에 전달해야 합니다.

오류: NotRegistered

NotRegistered는 여러 번의 등록이 발생하고 두 번째 등록이 첫 번째 토큰을 무효화할 때도 발생할 수 있습니다.

푸시 알림이 전송되었지만 사용자의 기기에 표시되지 않음

이러한 문제가 발생하는 데에는 몇 가지 이유가 있습니다:

애플리케이션이 강제 종료됨

시스템 설정을 통해 애플리케이션을 강제 종료하면 푸시 알림이 전송되지 않습니다. 앱을 다시 실행하면 기기에서 푸시 알림을 다시 받을 수 있습니다.

BrazeFirebaseMessagingService가 등록되지 않음

푸시 알림이 표시되려면 BrazeFirebaseMessagingService가 AndroidManifest.xml에 올바르게 등록되어 있어야 합니다:

<service android:name="com.braze.push.BrazeFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

방화벽이 푸시를 차단하고 있음

커스텀 알림 팩토리에서 null 반환

커스텀 알림 팩토리를 구현한 경우 null을 반환하지 않는지 확인하세요. null을 반환하면 알림이 표시되지 않습니다.

메시지 전송 후 “푸시 등록” 사용자가 더 이상 활성화되지 않음

이런 일이 발생하는 데에는 몇 가지 이유가 있습니다:

애플리케이션이 제거됨

사용자가 애플리케이션을 제거했습니다. 이렇게 하면 FCM 푸시 토큰이 무효화됩니다.

잘못된 Firebase 클라우드 메시징 서버 키

Firebase 플랫폼의 "설정"과 "클라우드 메시징" 아래에 서버 ID와 서버 키가 표시됩니다.

푸시 클릭이 기록되지 않음

커스텀 푸시 핸들러를 구현한 경우, 네이티브 푸시 분석을 올바르게 보존하고 있는지 확인하세요.

딥링크가 작동하지 않음

딥링크 구성 확인

딥링크는 ADB로 테스트할 수 있습니다. 다음 명령어로 딥링크를 테스트하는 것이 좋습니다:

adb shell am start -W -a android.intent.action.VIEW -d "THE_DEEP_LINK" THE_PACKAGE_NAME

딥링크가 작동하지 않으면 딥링크가 잘못 구성된 것일 수 있습니다. 잘못 구성된 딥링크는 Braze 푸시를 통해 전송할 때 작동하지 않습니다.

커스텀 처리 로직 확인

백 스택 동작 비활성화

<bool name="com_braze_push_deep_link_back_stack_activity_enabled">false</bool>

문제 해결

작업 전환기에서 앱을 닫은 후 푸시가 표시되지 않음

작업 전환기에서 앱을 닫은 후 푸시 알림이 더 이상 표시되지 않는 경우, 앱이 디버그 모드에 있을 가능성이 높습니다. .NET MAUI는 디버그 모드에서 스캐폴딩을 추가하여 프로세스가 종료된 후 앱이 푸시를 수신하지 못하도록 합니다. 릴리스 모드에서 앱을 실행하면 작업 전환기에서 앱을 닫은 후에도 푸시가 표시됩니다.

커스텀 알림 팩토리가 올바르게 설정되지 않음

커스텀 알림 팩토리(및 모든 델리게이트)는 C#과 Java 간에 올바르게 작동하려면 Java.Lang.Object를 확장해야 합니다. 자세한 내용은 Java 인터페이스 구현에 대한 Xamarin 문서를 참조하세요.

푸시 알림의 줄 바꿈

Liquid 태그를 사용하여 푸시 알림을 작성할 때, Liquid 태그에 인접한 줄 바꿈은 메시지가 전송되기 전에 자동으로 제거됩니다. 푸시 알림 작성기에서는 편집 중 메시지의 가독성을 유지하기 위해 이러한 줄 바꿈이 다시 추가됩니다. 메시지를 저장할 때 Liquid 태그 주변에 줄 바꿈이 표시되는 경우, 이는 정상적인 동작입니다.

New Stuff!