プッシュ通知のトラブルシューティング

Braze/APNsワークフローの理解

Apple Push Notification service（APNs）は、Appleのプラットフォーム上で動作するアプリケーションにプッシュ通知を送信するためのインフラです。ここでは、ユーザーのデバイスでプッシュ通知が有効になる仕組みと、Brazeがプッシュ通知を送信する方法の簡略化された構造を説明します。

1. プッシュ証明書とプロビジョニングプロファイルを設定します
2. デバイスがAPNsに登録し、Brazeにプッシュトークンを提供します
3. Brazeプッシュキャンペーンを開始します
4. Brazeが無効なトークンを削除します

ステップ1：プッシュ証明書とプロビジョニングプロファイルの設定

アプリを開発するには、プッシュ通知を有効にするためのSSL証明書を作成します。この証明書は、アプリのビルドに使用されるプロビジョニングプロファイルに含まれ、Brazeダッシュボードにもアップロードする必要があります。この証明書により、Brazeはお客様に代わってプッシュ通知を送信する権限があることをAPNsに伝えることができます。

プロビジョニングプロファイルと証明書には、開発用と配布用の2種類があります。混乱を避けるため、配布用のプロファイルと証明書のみを使用することをお勧めします。開発用と配布用で異なるプロファイルと証明書を使用する場合は、ダッシュボードにアップロードされた証明書が、現在使用しているプロビジョニングプロファイルと一致していることを確認してください。

警告

プッシュ証明書の環境（開発用と本番用）を変更しないでください。プッシュ証明書を誤った環境に変更すると、ユーザーのプッシュトークンが誤って削除され、プッシュ通知で到達できなくなる可能性があります。

ステップ2：デバイスがAPNsに登録し、Brazeにプッシュトークンを提供する

ユーザーがアプリを開くと、プッシュ通知を受け入れるかどうかのプロンプトが表示されます。このプロンプトを受け入れると、APNsはその特定のデバイスに対してプッシュトークンを生成します。Swift SDKは、デフォルトの自動フラッシュポリシーを使用するアプリに対して、プッシュトークンを即座に非同期で送信します。ユーザーに関連付けられたプッシュトークンを取得すると、そのユーザーはダッシュボードのユーザープロファイルのエンゲージメントタブに「Push Registered」として表示され、Brazeキャンペーンからプッシュ通知を受信する資格を得ます。

注

macOS 13以降、特定のデバイスでは、Xcode 14上で動作するiOS 16シミュレーターでプッシュ通知をテストできます。詳細については、Xcode 14リリースノートを参照してください。

プッシュトークン生成に関する考慮事項

• ユーザーが別のデバイスにアプリをインストールした場合、Brazeは同じ方法で別のトークンを作成してキャプチャします。
• ユーザーがアプリを再インストールした場合、SDKは新しいトークンを生成してBrazeに渡します。ただし、APNsとBrazeは元のトークンを引き続き有効として記録する場合があります。
• ユーザーがアプリをアンインストールした場合、Brazeはすぐに通知を受け取らず、APNsがトークンを無効にするまでトークンは有効として表示されます。
• ある時点で、APNsは古いトークンを無効にします。Brazeはこれを制御したり、可視化したりすることはできません。

ステップ3：Brazeプッシュキャンペーンの起動

プッシュキャンペーンが起動されると、Brazeはメッセージを配信するためにAPNsにリクエストを送信します。具体的には、ユーザーの最新のデバイスに送信が選択されていない限り、現在有効な各プッシュトークンに対してリクエストがAPNsに渡されます。BrazeがAPNsから成功レスポンスを受信すると、ユーザープロファイルに配信成功を記録しますが、以下の理由によりユーザーが実際のメッセージを受信していない場合があります。

• デバイスの電源がオフになっている。
• デバイスがインターネット（Wi-Fiまたはセルラー）に接続されていない。
• 最近アプリをアンインストールした。

Brazeは、ダッシュボードにアップロードされたSSLプッシュ証明書を使用して認証を行い、提供されたプッシュトークンにプッシュ通知を送信する権限があることを確認します。デバイスがオンラインの場合、キャンペーンが送信された直後に通知を受信するはずです。Brazeは通知のデフォルトのAPNs有効期限を30日に設定しています。

ステップ4：無効なトークンの削除

メッセージを送信しようとしたプッシュトークンのいずれかが無効であるとAPNsから通知された場合、それらのトークンを関連付けられていたユーザープロファイルから削除します。

注

トークンが未登録になった場合でも、APNsが最初に成功ステータスを返すのは正常な動作です。APNsはトークンの無効化イベントをすぐには報告しません。APNsは、ユーザーのプライバシーを保護し、アプリのアンインストールの追跡を防止するために設計されたランダムなスケジュールで、無効なトークンに対する410ステータスの返却を意図的に遅延させます。APNsが410ステータスを返すまで、未登録のトークンに対して安全に通知を送信し続けることができます。

プッシュエラーログの使用

メッセージアクティビティログでは、キャンペーンや送信に関連するメッセージ（特にエラーメッセージ）を確認できます。これにはプッシュ通知のエラーも含まれます。このエラーログにはさまざまな警告が表示され、キャンペーンが期待どおりに動作しない理由を特定するのに非常に役立ちます。エラーメッセージを選択すると、特定のインシデントのトラブルシューティングに役立つ関連ドキュメントにリダイレクトされます。

ここで表示される一般的なエラーには、「Received Unregistered Sending to Push Token」などのユーザー固有の通知があります。

さらに、Brazeはユーザープロファイルのエンゲージメントタブにプッシュ変更ログも提供しています。この変更ログでは、トークンの無効化、プッシュ登録エラー、トークンが新しいユーザーに移動されたことなど、プッシュ登録の動作に関するインサイトを確認できます。

メッセージアクティビティログのエラー

Received unregistered sending to push token

• AppDelegate.braze?.notifications.register(deviceToken:)メソッドからBrazeに送信されるプッシュトークンが有効であることを確認してください。メッセージアクティビティログでプッシュトークンを確認できます。6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6のような、文字と数字が混在する長い文字列のように表示されるはずです。プッシュトークンが異なる形式の場合は、Brazeにプッシュトークンを送信するためのコードを確認してください。
• プッシュプロビジョニングプロファイルがテスト中の環境と一致していることを確認してください。ユニバーサル証明書は、Brazeダッシュボードで開発用または本番用のAPNs環境のいずれかに送信するように設定できます。本番アプリに開発用証明書を使用したり、開発アプリに本番用証明書を使用したりすると動作しません。
• Brazeにアップロードしたプッシュトークンが、プッシュトークンの送信元アプリのビルドに使用したプロビジョニングプロファイルと一致していることを確認してください。

Device token not for topic

APNsは、プッシュトークンが認証情報に設定されたトピック（バンドルID）と一致しない場合にDeviceTokenNotForTopic（HTTPステータス400）を返します。Brazeはメッセージアクティビティログまたはプッシュ配信ログにこれをDeviceTokenNotForTopicとして表示する場合があります。

不一致を解決するには：

1. アプリのバンドルIDがBrazeのアプリバンドルID（設定 > アプリ設定 > プッシュ通知設定）と一致していることを確認します。
2. アプリのビルドに使用したプロビジョニングプロファイルに、そのバンドルIDのプッシュ機能が含まれていることを確認します。
3. Brazeにアップロードしたプッシュ認証情報がアプリの環境（開発用と本番用）と一致していることを確認します。
4. .p8キーの場合、BrazeのチームIDとキーIDがApple Developerアカウントと一致していることを確認します。
5. 認証情報がローテーションまたは失効された場合は、有効な.p8キーまたは.p12証明書を再アップロードします。

可能な場合は.p8認証キーを使用することをお勧めします。認証情報の種類とダッシュボードのステータスインジケーターについては、.p8認証キーへの移行を参照してください。

BadDeviceToken sending to push token

BadDeviceTokenはAPNsのエラーコードであり、Brazeから発生するものではありません。このレスポンスが返される理由はいくつか考えられ、以下のようなものがあります。

• アプリが、ダッシュボードにアップロードされた認証情報に対して無効なプッシュトークンを受信しました。
• このワークスペースでプッシュが無効になっていました。
• ユーザーがプッシュをオプトアウトしました。
• アプリがアンインストールされました。
• Appleがプッシュトークンを更新し、古いトークンが無効になりました。
• アプリが本番環境用にビルドされていますが、Brazeにアップロードされたプッシュの認証情報が開発環境用に設定されています（またはその逆）。

プッシュ登録の問題

プッシュ登録プロンプトが表示されない

アプリがプッシュ通知の登録を促すプロンプトを表示しない場合、プッシュ登録の統合に問題がある可能性があります。ドキュメントに従い、プッシュ登録が正しく統合されていることを確認してください。また、コード内にブレークポイントを設定して、プッシュ登録コードが実行されていることを確認することもできます。

ダッシュボードに「プッシュ登録済み」ユーザーが表示されない（メッセージ送信前）

アプリがプッシュ通知を許可するように正しく設定されていることを確認してください。確認すべき一般的な障害ポイントは以下のとおりです。

• アプリがプッシュ通知の許可を求めるプロンプトを表示しているか確認してください。通常、このプロンプトはアプリの初回起動時に表示されますが、別の場所に表示されるようにプログラムすることもできます。表示されるべき場所に表示されない場合、アプリのプッシュ機能の基本設定に問題がある可能性があります。
  • プッシュ統合の手順が正常に完了していることを確認してください。
  • アプリのビルドに使用したプロビジョニングプロファイルにプッシュの権限が含まれていることを確認してください。Apple開発者アカウントから利用可能なすべてのプロビジョニングプロファイルを取得していることを確認してください。確認するには、以下の手順を実行してください。
    1. Xcodeで、Preferences > Accountsに移動します（またはキーボードショートカットCommand+,を使用します）。
    2. 開発者アカウントに使用しているApple IDを選択し、View Detailsをクリックします。
    3. 次のページで、 Refreshをクリックし、利用可能なすべてのプロビジョニングプロファイルを取得していることを確認します。
• アプリでプッシュ機能が正しく有効化されていることを確認してください。
• プッシュプロビジョニングプロファイルがテスト中の環境と一致していることを確認してください。ユニバーサル証明書は、Brazeダッシュボードで開発用または本番用のAPNs環境のいずれかに送信するように設定できます。本番アプリに開発用証明書を使用したり、開発アプリに本番用証明書を使用したりしても機能しません。
• コード内にブレークポイントを設定して、registerPushTokenメソッドが呼び出されていることを確認してください。
• 実機を使用してテストしていること（シミュレーターではプッシュは動作しません）、およびネットワーク接続が良好であることを確認してください。

プッシュ通知が送信されたがユーザーのデバイスに表示されない

メッセージ送信後に「プッシュ登録済み」ユーザーが無効になる

これは、ユーザーのプッシュトークンが無効であることを示している可能性があります。これはいくつかの理由で発生する可能性があります。

ダッシュボードとアプリの証明書の不一致

ダッシュボードにアップロードしたプッシュ証明書が、アプリのビルドに使用されたプロビジョニングプロファイルのものと異なる場合、APNsはトークンを拒否します。正しい証明書をアップロードしたことを確認し、別のテスト通知を試みる前にアプリで別のセッションを完了してください。

アプリがアンインストールされた

ユーザーがアプリをアンインストールした場合、プッシュトークンは無効になり、次回の送信時に削除されます。

プロビジョニングプロファイルの再生成

最後の手段として、最初からやり直して新しいプロビジョニングプロファイルを作成することで、複数の環境、プロファイル、アプリを同時に扱うことで生じる設定エラーを解消できます。プッシュ通知の設定には多くの「可動部分」があるため、最初からやり直すのが最善の場合もあります。これにより、トラブルシューティングを続ける必要がある場合に問題を切り分けることもできます。

「プッシュ登録済み」ユーザーにメッセージが配信されない

アプリがフォアグラウンドにある

UserNotificationsフレームワークを介してプッシュを統合していないiOSバージョンでは、プッシュメッセージの受信時にアプリがフォアグラウンドにある場合、メッセージは表示されません。テストメッセージを送信する前に、テストデバイスでアプリをバックグラウンドにしてください。

テスト通知のスケジュールが正しくない

テストメッセージに設定したスケジュールを確認してください。ローカルタイムゾーン配信またはインテリジェントタイミングに設定されている場合、まだメッセージを受信していない（またはメッセージ受信時にアプリがフォアグラウンドにあった）可能性があります。

テスト対象のアプリでユーザーが「プッシュ登録済み」でない

テストメッセージを送信しようとしているユーザーのユーザープロファイルを確認してください。エンゲージメントタブに「プッシュ可能なアプリ」の一覧が表示されるはずです。テストメッセージを送信しようとしているアプリがこの一覧に含まれていることを確認してください。ユーザーは、ワークスペース内のいずれかのアプリのプッシュトークンを持っている場合に「プッシュ登録済み」と表示されるため、これは偽陽性の可能性があります。

以下の表示は、プッシュ登録に問題があるか、プッシュ送信後にユーザーのトークンがAPNsによって無効としてBrazeに返されたことを示しています。

プッシュクリックが記録されない

• プッシュ通知の統合ステップに従っていることを確認してください。
• Brazeは、フォアグラウンドでサイレントに受信されたプッシュ通知を処理しません（UserNotificationsフレームワーク導入前のデフォルトのフォアグラウンドプッシュ動作）。つまり、リンクは開かれず、プッシュクリックも記録されません。アプリがまだUserNotificationsフレームワークを統合していない場合、アプリの状態がUIApplicationStateActiveのときにBrazeはプッシュ通知を処理しません。アプリがプッシュ処理メソッドの呼び出しを遅延させないようにしてください。遅延させると、Swift SDKがプッシュ通知をサイレントフォアグラウンドプッシュイベントとして扱い、処理しない場合があります。

ディープリンクが機能しない

すべてのチャネル（ユニバーサルリンク、カスタムスキーム、メール、Branchなどのサードパーティプロバイダーを含む）にわたる包括的なトラブルシューティングについては、ディープリンクのトラブルシューティングを参照してください。

プッシュクリックからのWebリンクが開かない

プッシュ通知内のリンクをWebビューで開くには、ATSに準拠している必要があります。WebリンクがHTTPSを使用していることを確認してください。詳細については、ATSコンプライアンスを参照してください。

プッシュクリックからのディープリンクが開かない

ディープリンクを処理するコードの大部分は、プッシュの開封も処理します。まず、プッシュの開封が記録されていることを確認してください。記録されていない場合は、その問題を修正してください（修正によりリンク処理の問題も解決されることが多いです）。

開封が記録されている場合は、ディープリンク全般の問題なのか、ディープリンクのプッシュクリック処理の問題なのかを確認してください。これを確認するには、アプリ内メッセージのクリックからディープリンクが機能するかどうかをテストしてください。