문제 해결

Braze/APNs 워크플로 이해하기

Apple 푸시 알림 서비스(APNs)는 iOS 및 OS X 애플리케이션에 푸시 알림을 전송하기 위한 Apple의 인프라입니다. 사용자의 기기에서 푸시 알림이 활성화되는 방법과 Braze가 푸시 알림을 전송하는 방법에 대한 간략한 구조는 다음과 같습니다:

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

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

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

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

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

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

3단계: Braze 푸시 Campaign 시작

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

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

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

푸시 오류 로그 활용하기

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

여기에서 볼 수 있는 일반적인 오류에는 “푸시 토큰으로 미등록 발송 수신”과 같은 사용자별 알림이 포함됩니다.

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

푸시 등록 문제

앱의 푸시 등록 로직에 대한 검증을 추가하려면 푸시 단위 테스트를 구현하세요.

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

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

대시보드에 “푸시 등록됨” 사용자가 표시되지 않음

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

푸시 알림을 수신하지 못하는 기기

푸시 알림 발송 후 사용자가 더 이상 “푸시 등록” 상태가 아닌 경우

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

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

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

앱 삭제

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

프로비저닝 프로필 재생성

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

푸시 알림 발송 후에도 사용자가 여전히 “푸시 등록” 상태인 경우

앱이 포그라운드에 있는 경우

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

테스트 알림 스케줄이 잘못 설정된 경우

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

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

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

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

푸시 메시지가 발송되지 않음

푸시 알림이 발송되지 않는 문제를 해결하려면 푸시 문제 해결을 참조하세요.

메시지 활동 로그 오류

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

• [[Appboy sharedInstance] registerPushToken:] 메서드에서 Braze로 전송되는 푸시 토큰이 유효한지 확인하세요. 메시지 활동 로그에서 푸시 토큰을 확인할 수 있습니다. 푸시 토큰은 6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6와 같이 문자와 숫자가 혼합된 긴 문자열 형태여야 합니다. 푸시 토큰이 다르게 보인다면, Braze에 푸시 토큰을 전송하는 코드를 확인하세요.
• 푸시 프로비저닝 프로필이 테스트 중인 환경과 일치하는지 확인하세요. 유니버설 인증서는 Braze 대시보드에서 개발 또는 프로덕션 APN 환경으로 발송하도록 구성할 수 있습니다. 프로덕션 앱에 개발 인증서를 사용하거나 개발 앱에 프로덕션 인증서를 사용하면 작동하지 않습니다.
• Braze에 업로드한 푸시 토큰이 푸시 토큰을 전송한 앱을 빌드할 때 사용한 프로비저닝 프로필과 일치하는지 확인하세요.

기기 토큰이 해당 토픽에 맞지 않음

이 오류는 앱의 푸시 인증서와 번들 ID가 일치하지 않음을 나타냅니다. Braze에 업로드한 푸시 인증서가 푸시 토큰을 전송한 앱을 빌드할 때 사용한 프로비저닝 프로필과 일치하는지 확인하세요.

푸시 토큰으로 발송 시 BadDeviceToken

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

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

푸시 전달 후 문제

앱의 푸시 처리에 대한 검증을 추가하려면 푸시 단위 테스트를 구현하세요.

푸시 클릭이 기록되지 않음

• iOS 10에서만 발생하는 경우, iOS 10에 대한 푸시 통합 단계를 따랐는지 확인하세요.
• Braze는 포그라운드에서 자동으로 수신된 푸시 알림을 처리하지 않습니다(예: UserNotifications 프레임워크 이전의 기본 포그라운드 푸시 동작). 이는 링크가 열리지 않고 푸시 클릭이 기록되지 않음을 의미합니다. 앱이 아직 UserNotifications 프레임워크를 통합하지 않은 경우, Braze는 앱 상태가 UIApplicationStateActive일 때 푸시 알림을 처리하지 않습니다. 앱이 푸시 처리 메서드 호출을 지연시키지 않도록 해야 합니다. 그렇지 않으면 iOS SDK가 푸시 알림을 자동 포그라운드 푸시 이벤트로 처리하여 제대로 핸들링하지 못할 수 있습니다.

푸시 클릭에서 웹 링크가 열리지 않음

iOS 9 이상에서는 웹 뷰에서 열리려면 링크가 ATS를 준수해야 합니다. 웹 링크가 HTTPS를 사용하는지 확인하세요. 자세한 내용은 ATS 준수 문서를 참조하세요.

푸시 클릭에서 딥링크가 열리지 않음

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

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

직접 열람이 거의 없거나 전혀 없음

최소 한 명의 사용자가 iOS 푸시 알림을 열었지만 Braze에 _직접 열람_이 거의 또는 전혀 기록되지 않는 경우, SDK 통합에 문제가 있을 수 있습니다. _직접 열람_은 테스트 발송이나 자동 푸시 알림에 대해서는 기록되지 않는다는 점을 유의하세요.

• 메시지가 자동 푸시 알림으로 발송되고 있지 않은지 확인하세요. 자동 푸시로 간주되지 않으려면 메시지의 제목이나 본문에 텍스트가 있어야 합니다.
• 푸시 통합 가이드에서 다음 단계를 다시 확인하세요:
  • 푸시 등록: 모든 앱 실행 시, 가급적 application:didFinishLaunchingWithOptions: 내에서 3단계의 코드가 실행되어야 합니다. UNUserNotificationCenter.current()의 delegate 속성정보는 UNUserNotificationCenterDelegate를 구현하고 (void)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: 메서드를 포함하는 오브젝트에 할당되어야 합니다.
  • 푸시 처리 활성화: (void)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: 메서드가 구현되었는지 확인하세요.