デバッグ

GitHub

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

通知が登録されない、届かない、表示されない、または Capgo の統計が更新されない場合は、このチェックリストを使用してください。

デバイスレコードから確認する

ネイティブの code をデバッグする前に、Capgo でデバイスが確認できるか確認してください。

アプリを開き、テスト対象のユーザーとしてサインインします。
呼び出す CapgoNotifications.register(...) サインイン後。
Capgo で、以下を開きます： 通知 > 送信先検索.
同じ外部顧客ID（external customer ID）で検索してください。

以下の条件を満たす、少なくとも1つのアクティブなデバイスが表示されるはずです：

recipientKey
deviceKey
プラットフォーム android または ios
権限の状態
アプリのバージョン
プラグインのバージョン
タグと属性

ルックアップでデバイスが見つからない場合、そのユーザーを送信先に指定することはできません。

一時的なデバッグ用リスナーの追加

テスト中に一時的なリスナーを追加します。リリース前には不要なログを削除してください。

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

情報の収集

チームや Capgo のサポートとデバッグを行う際は、以下を準備してください：

Capgo のアプリID。
アプリのパッケージID、またはiOSのbundle ID。
デバイスのプラットフォームとOSバージョン。
アプリのバージョンとビルド番号。
プラグインのバージョン。
外部のカスタマーID。
recipientKey と deviceKey 登録時、または受信者検索時のもの。
キャンペーンID、または通知ID。
アプリの状態（フォアグラウンド、バックグラウンド、強制終了、または新規インストール）。
問題が再現した際のデバイスログ。

デバイスログの使用

テスト通知を送信する間、実機を接続したままにしてください。

Androidの場合:

Android StudioのLogcatを開きます。
アプリのパッケージIDでフィルタリングします。
通知の権限リクエスト、ネイティブトークンの更新、メッセージの受信、およびJavaScriptリスナーのログを確認してください。
通知が表示されない場合は、まず通知チャンネルの重要度とAndroid 13以降の権限状態を確認してください。

iOSの場合:

実機を使用してXcodeからアプリを実行します。
Xcodeのコンソールを開くか、 デバイスとシミュレーター ログ。
Bundle IDでフィルタリングし、 CapgoNotifications.
確認 AppDelegate.swift リモート通知が転送されていること、およびBackground ModeのCapabilityが有効であることを確認してください。

まずフォアグラウンドでのテストを1回、次にバックグラウンドでのテストを1回、最後にサイレントなupdate-checkのテストを1回実行してください。この順序でテストを行うことで、JavaScriptのリスナーの問題とOSのバックグラウンド配信制限の問題を切り分けることができます。

登録に関する問題

CLI のセットアップが完了しませんでした

以下のファイルが含まれているフォルダからセットアップコマンドを実行してください capacitor.config.*:

npx @capgo/cli@latest notifications setup com.example.app

コマンドでアプリIDを推測できない場合は、上記のように明示的に指定してください。パッケージのインストールに失敗する場合は、パッケージ名が @capgo/capacitor-notifications、npm レジストリが https://registry.npmjs.org、ネットワーク接続を確認してから、コマンドを再実行してください。

受信者検索にデバイスが表示されない場合

確認：

register は、アプリに認証済みユーザーが存在する状態で呼び出されます。
externalId ダッシュボードで検索しているユーザーIDと一致しているか確認してください。
identityProof は、同じユーザーに対してバックエンドから発行されたもので、 appId と externalId.
appId における configure は、Capgo アプリと一致しています。
consent に設定されていません false ユーザーがオプトアウトしていない限り、
デバイスは〜へのネットワークアクセスがあります https://api.capgo.app.
ネイティブのプッシュトークンが作成されました。〜を使用してください。 registrationChanged を使用してトークンのリフレッシュを確認します。

無効な Identity Proof

Proof は Capgo の app ID および外部 ID に紐付けられています。どちらかの値が変更された場合は、新しい Proof を mint してください。

一つの Proof を永続的にキャッシュしたり、アプリ間で使い回したりしないでください。ログイン後にバックエンドから mint してアプリに返し、〜を呼び出してください。 register.

デバイスは登録済みですが、権限が拒否されています

ユーザーが権限を拒否した場合でも、プラグインはデバイスの状態を登録できます。デバイス自体は確認できますが、通知は表示されません。

OSのプロンプトを表示する前に、パーミッションの事前説明画面（primer screen）を表示しましょう。ユーザーが得られるメリットを説明した上で、適切なタイミングで権限をリクエストしてください。

配信に関する問題

キューに入ったまま送信されない

確認：

プラットフォームの認証ステータスは configured Capgo になっています。
ワーカー環境に、ダッシュボードに表示されているものと全く同じシークレット参照が含まれています。
アプリ内のパッケージIDまたはBundle IDが、プラットフォームのプッシュ設定と一致しています。
ターゲット層が、少なくとも1台以上の有効なデバイスに紐付いています。
キャンペーンが、デバイスが持っていないタグやセグメントに限定されていません。

送信済みだが受信できていない場合

確認：

デバイスがオンラインであること。
ユーザーによってアプリが強制終了されていないこと。
OSの通知権限が許可されていること。
テスト中にAndroidのバッテリー制限によってアプリがブロックされていないこと。
iOSの低電力モードやバックグラウンド更新の制限が、バックグラウンド配信に影響していないこと。
同じcollapse IDを持つ別の通知によって、通知が上書きされていないこと。

ネイティブのプッシュプラットフォームは、通知を受け取った後でも、配信の遅延、スロットリング、結合、またはドロップを行う可能性があります。プロバイダー側の「受理済み」統計は、デバイスに表示された証明ではなく、あくまで「配信に向けて受理された」ものとして扱ってください。

受信済みだが表示されていない場合

確認：

アプリがフォアグラウンド状態ではありませんでした。通常、フォアグラウンド通知はJavaScriptに渡され、アプリ側で表示するUIを決定します。
Androidの通知チャンネルの重要度が、アラートを表示するのに十分な高さに設定されています。
Android 13以降の通知権限が許可されています。
iOSの集中モード、通知要約、またはアプリごとの通知設定によって通知が非表示になっています。
テスト中に、バッジのクリアやアプリ起動時のロジックによって通知が削除されています。

バックグラウンド通知の問題

バックグラウンドコールバックが実行されない

バックグラウンド通知はベストエフォートです。OSによってスキップされる可能性があります。

確認：

iOSでは Background Modes > Remote notifications が有効です。
iOSと AppDelegate.swift リモート通知を以下に転送します： CapgoNotificationsRemoteNotification.
iOSのバックグラウンド動作は、実機でテストしてください。
ユーザーによってアプリが強制終了されていないこと。
バックグラウンドハンドラーが呼び出します： finish().
コールバック内の処理は、短時間で、ネットワークに安全かつ、べき等（idempotent）である必要があります。

iOSでは、通知の送信頻度が高すぎる場合や、処理に時間がかかりすぎる場合、またはユーザーがアプリをほとんど開かない場合、バックグラウンドプッシュが制限されることがあります。これはプラットフォームの仕様通りの挙動です。

バックグラウンド処理が開始されたが完了していない

統計情報に表示される場合、 background_started なしで background_finishedJavaScript ハンドラーが例外をスローしたか、タイムアウトしたか、呼び出しを行わなかった可能性があります。 finish().

ハンドラーを以下でラップしてください： try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

サイレントアップデートチェックの問題

アップデートチェック通知は届くが、アップデートがインストールされない

確認：

@capgo/capacitor-updater がインストールされ、設定されています。
autoUpdater が true または enableUpdaterIntegration が呼び出されました。
アプリの通知設定により、プッシュによるアップデート確認が可能です。
対象デバイスが、想定通りのチャンネルに属しています。
アプリには Capgo で利用可能な新しいbundleがあります。
アップデートのインストールモードが正しい： next 次回の再起動またはバックグラウンドサイクルに備えてキューに入ります, set アップデーターが安全にインストールできるようになり次第、インストールされます。

アプリ起動中に手動チェックを実行してください：

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

手動チェックが結果を返す場合は unavailable、まずアップデータープラグインの設定を確認してください。

バッジに関する問題

確認：

受信者の検索時に、ターゲットが正しいデバイスに解決されている。
テスト対象のランチャーまたはホーム画面で、プラットフォームがアプリバッジをサポートしている。
ユーザーがOSの通知設定でバッジを無効にしていない。
アプリ起動時にバッジが即座にクリアされていない。
ローカルでの呼び出しと、 setBadge バックエンドへのバッジ送信との間で競合が発生している。

統計に関する問題

統計が重複しているように見える

通知の送信はat-least-onceです。キューの再試行やプラットフォーム側の再試行によって送信が重複する可能性があります。アプリ側の処理を冪等にする必要がある場合は、通知IDとcollapse IDを使用してください。

古いデバイスで統計が欠落する

Analytics Engineのレジストリはアクティブなデバイス向けであり、永続的なデータベースではありません。プラグインは、アプリ起動時、トークン更新時、外部ID変更時、そしてアクティブデバイスの保持期間が切れる前に定期的に登録を更新する必要があります。

Openイベントが欠落する

確認：

通知には安定した id.
notificationOpened リスナーがアプリ起動時に登録されている。
プラグインが検知する前に、アプリがネイティブのopenフローを独自の code で置き換えていない。
ユーザーが手動でアプリを開いたのではなく、実際に通知をタップした。

API デバッグコマンド

受信者を検索:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

統計を取得:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

フォアグラウンドテストを送信:

curl -X POST 'https://api.capgo.app/notifications/send' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "payload": {
      "title": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

よくある根本原因

症状	考えられる原因
デバイスが検索で見つからない	`register` 呼び出されていない、proofの不一致、consentがfalse、App IDの不一致。
権限が拒否されました	OSのプロンプトが拒否されたか、まだリクエストされていません。
キューに入っていますが、送信統計がありません	プラットフォームの認証情報が不足しているか、無効になっています。
送信済みですが、受信統計がありません	デバイスがオフライン、OSのスロットリング、アプリの強制停止、またはトークンが無効。
フォアグラウンド通知のログはあるが、バナーが表示されない	アプリがフォアグラウンドにあり、独自のインアプリUIを表示する必要があります。
iOSではバックグラウンド実行は行われません	権限不足、AppDelegateの転送設定漏れ、アプリの強制終了、またはOSによる制限。
アップデートのチェックが動作しない	Updaterの統合が無効、新しいbundleがない、チャンネルが不一致、またはインストールモードの誤解。
バッジがリセットされる	アプリ起動時の code によるバッジ消去、またはローカルとバックエンドの書き込み競合。

デバッグの続きを読む

デバイスの登録とテスト通知の成功を確認したら、以下を使用してください：スタートガイドバッジ、キャンペーンのターゲティング、およびサイレントアップデートのチェックを本番アプリに組み込むために使用します。