デバッグ

通知が登録されず、届きず、表示されず、または更新されず、Capgo統計が更新されない場合に使用するチェックリストです。

デバイスレコードから始めましょう

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

1. アプリを開き、テストしたいユーザーとしてサインインしてください。
2. 「 CapgoNotifications.register(...) サインイン後
3. In Capgo、開く 通知 > 受信者検索.
4. 外部顧客IDで検索する

__CAPGO_KEEP_0__で少なくとも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バンドルID
• デバイスのプラットフォームとOSバージョン
• アプリバージョンとビルド番号
• プラグインバージョン
• 外部顧客ID
• recipientKey と deviceKey 登録または受信者検索から。
• キャンペーンIDまたは通知ID。
• アプリが前景、バックグラウンド、強制終了、または新規インストールされていたかどうか。
• 問題を再現した実行のデバイスログ。

デバイスログを使用

実際のデバイスを1台接続して、テスト通知を送信しながら。

Androidの場合:

• Android StudioのLogcatを開く。
• アプリパッケージIDでフィルタリングする。
• 通知許可要求、ネイティブトークン更新、メッセージ受信、JavaScriptリスナーログを確認する。
• 表示される通知が表示されない場合、通知チャンネルの重要性とAndroid 13以降のパーミッション状態を確認してください。

iOSの場合:

• Xcodeから実機でアプリを実行してください。
• Xcodeコンソールまたは デバイスとシミュレータ ログを確認してください。
• バンドルIDをフィルタして CapgoNotifications.
• 確認してください。 AppDelegate.swift リモート通知が送信され、バックグラウンドモードの機能が有効になっていることを確認してください。

1回目のフォアグラウンドテスト、2回目のバックグラウンドテスト、3回目の静的更新チェックテストを順番に送信してください。この順序は、JavaScriptリスナーの問題とOSのバックグラウンド配信制限を区別するのに役立ちます。

登録問題

CLI セットアップが正常に完了しない

__CAPGO_KEEP_0__ セットアップコマンドを実行するフォルダからコマンドを実行してください capacitor.config.*:

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

コマンドがアプリIDを自動で推測できない場合は、上記のように明示的に指定してください。パッケージのインストールが失敗した場合は、パッケージ名を確認し、__CAPGO_KEEP_0__ レジストリが正しく設定されていることを確認してください @capgo/capacitor-notificationsnpm レジストリが正しく設定されていない可能性があります、パッケージ名を確認し、ネットワーク接続が正常であることを確認し、再度コマンドを実行してください https://registry.npmjs.org受信者検索リストにデバイスが表示されない

セクション「受信者検索リストにデバイスが表示されない」

ユーザーが認証された後、

• register ユーザーが認証された後、
• externalId は、ダッシュボードで検索したユーザーIDと一致します。
• identityProof は、同じであなたのバックエンドによってmintされた。 appId ページ externalId.
• appId で configure Capgoアプリと一致します。
• consent 設定されていません。 false ユーザーがオプトアウトしない限り。
• はネットワークアクセスを持ちます。 https://api.capgo.app.
• ネイティブプッシュトークンが作成されました。使用してトークン更新を確認してください。 registrationChanged 無効な身元証明

無効な身元証明

証明書はCapgoアプリIDと外部IDに紐づけられています。どちらかの値が変更された場合、新しい証明書を生成してください。

1つの証明書を永遠にキャッシュしないでください。アプリ内でログインした後、バックエンドから証明書を生成し、返却し、呼び出してください。 register.

デバイスが登録されたが、許可が拒否された

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

許可の前提条件画面を使用して、OSのプロンプトの前に許可を求めます。ユーザーが受け取るものを説明し、許可を求めるのはアクションが意味をなすときにのみ行ってください。

配信の問題

キューイング中ですが、送信されていません

確認してください:

• プラットフォーム認証情報の状態は configured in Capgo.
• ワーカー環境には、ダッシュボードによって示される精確なシークレット参照が含まれます。
• アプリのパッケージIDまたはバンドルIDは、プラットフォームのプッシュ設定と一致しています。
• ターゲットアウディエンスは、少なくとも1台のアクティブなデバイスに解決されます。
• キャンペーンは、デバイスが持っていないタグまたはセグメントに限定されていません。

送信されたが受け取られていない

確認する:

• デバイスはオンラインです。
• ユーザーによってアプリが強制終了されていません。
• OSの通知許可が付与されています。
• Androidのバッテリー制限がテスト中にアプリをブロックしていません。
• iOS Low Power Mode とバックグラウンドリフレッシュ制限は、バックグラウンド配信に影響していません。
• 通知は、同じコラプスIDを持つ別の通知によって置き換えられませんでした。

ネイティブプッシュプラットフォームは、通知を受け入れた後でも、配信を遅延させたり、制限したり、集約したり、または破棄したりすることができます。プロバイダーが受け入れた統計を “配信のために受け入れられた” と見なすのではなく、デバイスが表示したことを証明するものとして扱ってください。

受信したが表示されませんでした。

確認してください:

• アプリが前面に表示されていませんでした。通常、前面通知は JavaScript に配信され、UI を表示するためにアプリが決定することができます。
• Android の通知チャンネル重要度は、警告を表示するのに十分です。
• Android 13 以降の通知許可が付与されています。
• iOS の Focus、通知サマリー、またはアプリごとの通知設定が通知を隠していません。
• バッジクリアングまたはアプリを開くロジックが、配信された通知をテスト中に削除していません。

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

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

バックグラウンド通知はベストエフォートです。OSは通知をスキップすることができます。

確認:

• iOSには バックグラウンドモード > Remote通知 有効になっている。
• iOS AppDelegate.swift リモート通知を CapgoNotificationsRemoteNotification.
• 物理デバイスでiOSのバックグラウンド動作をテストします。
• ユーザーによってアプリが強制終了されていません。
• バックグラウンドハンドラーが呼び出されます。 finish().
• コールバック内で実行される作業は短時間、ネットワークセーフ、idempotentです。

iOSでは、バックグラウンドで送信した場合に多すぎる、時間がかかりすぎる、またはユーザーがアプリを開くことが少ない場合、プッシュが制限される可能性があります。これは、期待されるプラットフォームの動作です。

バックグラウンドが開始されたが完了していません。

統計が示す場合 background_started 、JavaScriptハンドラーが投げられた、タイムアウトした、または呼び出されなかったと考えられます。 background_finishedハンドラーをwrapする 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で利用可能な新しいバンドルがあります。
• アップデートのインストールモードは正しく設定されています: next 次の再起動またはバックグラウンドサイクルで待機しています。 set アップデートが安全に実行できるようになるまで、すぐにインストールされます。

アプリが開いている間、手動チェックを実行してください。

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

console.log(result)

手動チェックが正常に終了した場合 unavailable, アップデート プラグインの設定を確認してください。

バッジの問題

確認:

• 宛先の検索で正しいデバイスに解決されるかどうか
• プラットフォームは、テストしているホーム画面またはアプリ起動画面でアプリバッジをサポートしているか
• ユーザーはOSの通知設定でバッジを無効にしていないか
• アプリは起動時にバッジを即座にクリアしていないか
• ローカルで実行していることを確認してください setBadge バックエンドへの呼び出しはローカルで実行していないことを確認してください

統計問題

統計データが重複している

通知の送信は少なくとも1回行われます。キューのリトライとプラットフォームのリトライは、送信を重複させる可能性があります。通知IDとコラプスIDを使用して、アプリのアクションが idempotent であることを保証します。

古いデバイスの統計データが見つからない

分析エンジンのレジストリは、有効なデバイス用に設計されています。永久的なデータベースではありません。プラグインは、開始、トークン更新、外部IDの変更、有効なデバイスの保持期間前に定期的に登録を更新する必要があります。

オープンイベントが見つからない

確認:

• 通知には安定したリスナーがアプリ起動時に登録されている。 id.
• notificationOpened アプリはプラグインがそれを見た前に、ネイティブのオープン フローをカスタム __CAPGO_KEEP_0__ で置き換えていない。
• The app is not replacing the native open flow with custom code before the plugin sees it.
• __CAPGO_KEEP_0__ デバッグ コマンド

セクション「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 呼び出されていない、証明の不一致、同意が拒否された、アプリIDの不一致。
権限が拒否された	OSのプロンプトが拒否された、またはまだ要求されていない。
キューイング中だが送信統計なし	プラットフォームの資格情報が欠落しているか無効になっている
送信されたが受信統計なし	デバイスがオフライン、OSがスロットル、またはトークンが無効
フロアグラウンド通知のログが作成されるがバナーなし	アプリがフロアグラウンドで実行され、インアプリUIを表示する必要がある
iOSではバックグラウンドが実行されない	機能が欠落している、AppDelegateのフォワーディングが欠落している、またはアプリが強制終了した
アップデートチェックは何もしない	アップデーター統合が無効、バンドルが新しいものではない、またはチャンネルが間違っている
バッジのリセット	アプリ起動時にcodeがバッジをクリアするか、ローカルとバックエンドのバッジの書き込みが競合する

デバッグから続ける

デバイスが登録され、テスト通知が正常に動作したら、 は、プロダクションアプリにバッジ、キャンペーンターゲット、静的更新チェックを組み込むのに役立ちます。 編集