デバッグ

GitHub

このプラグインのインストール手順とフルマークダウンガイドを含む設定プロンプトをコピーする

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

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

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

アプリを開いて、テストしたいユーザーとしてサインインしてください。
サインイン後、「{call}」 CapgoNotifications.register(...) サインイン後
CapgoでCapgoを開きます。 通知 > 受信者検索.
外部顧客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バンドルID
デバイスプラットフォームとOSバージョン
アプリバージョンとビルド番号
プラグインバージョン
外部顧客ID
recipientKey と deviceKey 登録または受信者検索から。
キャンペーンIDまたは通知ID。
アプリが前景、バックグラウンド、強制終了、または新規インストールされていたかどうか。
問題を再現した実行のデバイスログ。

デバイスログを使用

実際のデバイスを1台接続して、テスト通知を送信してください。

Androidの場合:

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

iOSの場合:

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

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

登録問題

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

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

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

Capgo セットアップコマンドがアプリIDを推測できなかった場合、上記のように明示的に指定してください。パッケージのインストールが失敗した場合、Capgo があなたの npm アカウントでプライベートプレビューパッケージアクセスを有効にしていることを確認し、再度コマンドを実行してください。

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

確認してください:

register アプリが認証済みユーザーを持つ後で呼び出される
externalId 検索するユーザーIDがダッシュボードに一致する
identityProof 同じユーザーIDでバックエンドが発行した appId かつ externalId.
appId in configure Capgoアプリに一致します。
consent __CAPGO_KEEP_0__は設定されていません。 false __CAPGO_KEEP_0__が設定されていない場合
デバイスは__CAPGO_KEEP_0__にネットワーク接続があります。 https://api.capgo.app.
ネイティブプッシュトークンが作成されました。使用 registrationChanged トークン更新を確認するには

無効なID証明

証明はCapgoアプリIDと外部IDに紐付けられています。どちらの値も変更すると、新しい証明を生成する必要があります。

証明を永遠にキャッシュしないでください。証明をアプリ間で共有しないでください。ログイン後にバックエンドから証明を生成し、アプリに返し、 register.

デバイスが登録されましたが、パーミッションが拒否されました

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

OSのプロンプト前にパーミッションの説明画面を表示してください。ユーザーが得るものを説明し、許可を求めるのはアクションが意味をなすときに限ります。

配信の問題

キューイングされましたが、送信されませんでした

確認してください:

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

送信されたが受信されていない

確認:

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

Native pushプラットフォームは、通知を受け入れた後でも、遅延、制限、凝集、または配信を中止することができます。提供されたステータスを「配達の受け入れ」として扱い、デバイスが表示したことを証明するものではありません。

表示されなかった受信

確認:

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

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

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

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

確認:

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

iOSでは、バックグラウンド通知が遅延する可能性があります。大量の通知を送信したり、処理時間が長かったり、ユーザーがアプリを開くことが少なかったりすると、予想されるプラットフォームの動作です。

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

統計が示す場合 background_started 通知が送信されない場合 background_finishedJavaScriptハンドラーが投げられた、タイムアウトした、または呼び出されなかった可能性があります。 finish().

ハンドラーをwrapする try/finally:

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

静的更新チェックの問題

更新チェック通知が届いたが、更新がインストールされない

確認:

@capgo/capacitor-updater がインストールされ、設定されているかどうかです。
autoUpdater is true or enableUpdaterIntegration または
が呼び出されました。
の通知設定では、プッシュアップデートのチェックが可能です。
The app has a newer bundle available in Capgo.
のバンドルが__CAPGO_KEEP_0__で新しいバージョンが利用可能です。 next のアップデートのインストールモードは正しいです: set は、次の再起動またはバックグラウンドサイクルで待機しています。

は、安全にアップデートできるようになったらすぐにインストールされます。

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

console.log(result)

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

バッジの問題

確認:

宛先の検索で正しいデバイスに解決されるかどうか
テストしているランチャーまたはホーム画面のプラットフォームがアプリバッジをサポートしているか
ユーザーがOSの通知設定でバッジを無効にしていないか
アプリが起動時に即座にバッジをクリアしていないか
ローカル呼び出しとバックエンドのバッジ送信を競合させていないか setBadge Copy to clipboard

統計問題

統計値が重複している

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

古いデバイス用の統計値が見つからない

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

開いたイベントが見つからない

確認してください:

通知には安定した id.
notificationOpened リスナーはアプリ起動時に登録されます。
プラグインはアプリがカスタム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` 呼び出されていない、証明の不一致、同意が拒否され、App ID の不一致。
権限が拒否されました	OS のプロンプトが拒否されました、またはまだ要求されていません。
キューに追加されましたが、送信の統計はありません	プラットフォームのクレデンシャルが欠落している、または無効になっています。
送信されたが受信された統計がない	デバイスがオフライン、OSがスローダウン、またはトークンが無効です。
フロントグラウンド通知のログが出るがバナーは出ない	アプリがフロントグラウンドで実行されているため、自社のインアプリUIを表示する必要があります。
iOS上ではバックグラウンドが実行されない	機能が欠落している、AppDelegateのフォワーディングが欠落している、またはOSがスローダウンしている
アップデートチェックは何もしない	アップデーター統合が無効、バンドルが新しいものではない、またはチャンネルが間違っている
バッジがリセットされる	アプリ起動時にcodeがバッジやローカルとバックエンドのバッジの書き込みが競合する

デバッグから続けて

デバイスの登録とテスト通知の確認後、はじめにプロダクションアプリにバッジ、キャンペーンターゲット、静音の更新チェックを組み込むには

デバッグ

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

一時的なデバッグリスナーを追加します。

この情報を収集

デバイスログを使用

登録問題

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

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

無効なID証明

デバイスが登録されましたが、パーミッションが拒否されました

配信の問題

キューイングされましたが、送信されませんでした

送信されたが受信されていない

表示されなかった受信

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

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

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

静的更新チェックの問題

更新チェック通知が届いたが、更新がインストールされない

バッジの問題

統計問題

統計値が重複している

古いデバイス用の統計値が見つからない

開いたイベントが見つからない

API デバッグ コマンド

一般的な原因

デバッグから続けて

API デバッグコマンド