デバッグ

通知が登録されず、届きず、表示されず、または更新されず Capgo 統計を Capgo の場合に使用してください。

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

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

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

You should see at least one active device with:

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

If lookup returns no device, the send path cannot target that user.

テスト用に一時的なデバッグリスナーを追加する

テスト中はノイズの多いログを削除する前に、テスト用に一時的なリスナーを追加してください。

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台接続してテスト通知を送信するときは、常に1台のデバイスを接続してください。

Androidの場合:

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

iOSの場合:

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

1回の前景テスト、1回のバックグラウンドテスト、1回の静黙の更新チェックテストを実行してください。この順序は、JavaScriptリスナーの問題とOSのバックグラウンド配信制限を分離します。

登録問題

CLIセットアップが完了しなかった

セットアップコマンドをセットアップが完了しなかったフォルダから実行してください capacitor.config.*:

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

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

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

確認

• register アプリケーションが認証済みユーザーを持つ後、呼び出されます。
• externalId ダッシュボードで検索するユーザー ID と一致します。
• identityProof 同じで、バックエンドによって生成されました。 appId そして externalId.
• appId そして configure あなたの Capgo アプリケーションと一致します。
• consent は設定されていません。 false ユーザーがオプトアウトしない限り。
• デバイスはネットワークにアクセスできます。 https://api.capgo.app.
• ネイティブ プッシュ トークンが作成されました。 registrationChanged トークン リフレッシュを確認するには

無効なアイデンティティ プroof

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

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

デバイスが登録済みですが、許可が拒否されています

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

OSのプロンプト前にパーミッションのプリマー画面を使用してください。ユーザーに何が得られるのかを説明し、行動が意味をなす場合にのみパーミッションを求めます。

配信問題

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

確認:

• プラットフォーム認証情報の状態は configured in Capgo.
• アプリのパッケージIDまたはバンドルIDは、プラットフォームのプッシュ設定と一致しています。
• 対象ユーザーは少なくとも1台のアクティブなデバイスに解決されます。
• キャンペーンは、デバイスが持っていないタグまたはセグメントに制限されていません。
• __CAPGO_KEEP_0__.

届けられたが受け取られませんでした。

チェック:

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

ネイティブ プッシュ プラットフォームは、通知を受け入れても、後で遅延、制限、凝集、またはドロップすることができます。提供されたステータスを “配達済み” とみなすのではなく、デバイスが表示したことを証明するものではありません。

受け取られたが表示されませんでした。

Check:

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

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

バックグラウンドコールバックが実行されません

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

Check:

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

iOSでは、バックグラウンドプッシュが、多数送信したり、時間がかかったり、ユーザーがアプリを開く頻度が低かったりすると、制限されることがあります。これは、プラットフォームの予想される動作です。

バックグラウンドが始まったが完了しなかった

__CAPGO_KEEP_0__の統計が示す場合 background_started は background_finished、JavaScriptハンドラーが投げた、タイムアウトした、または呼び出されなかった finish().

ハンドラーを__CAPGO_KEEP_1__に Wrap try/finally:

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

静的更新チェックの問題

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

チェック:

• @capgo/capacitor-updater __CAPGO_KEEP_5__がインストールされており、設定されている
• autoUpdater __CAPGO_KEEP_5__がインストールされており、設定されている true または enableUpdaterIntegration その名は変わった。
• アプリの通知設定では、プッシュ更新のチェックが可能です。
• 期待しているチャンネルに属しているデバイスが対象です。
• アプリにはCapgoで利用可能な最新のバンドルがあります。
• アップデートモードは正しく設定されています: next 次の再起動またはバックグラウンドサイクルで、 set アップデートが安全に実行できる場合にすぐにインストールします。

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

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

console.log(result)

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

バッジ問題

チェック:

• __CAPGO_KEEP_0__は受信者検索で正しいデバイスに解決されます。
• __CAPGO_KEEP_0__プラットフォームは、テスト中のホーム画面またはアプリ起動画面のアプリバッジをサポートしています。
• __CAPGO_KEEP_0__ユーザーはOSの通知設定でバッジを無効にしていません。
• __CAPGO_KEEP_0__アプリは起動時にバッジを即座にクリアしていません。
• __CAPGO_KEEP_0__はローカルとバックエンドのバッジ送信の呼び出しを競合させていません。 setBadge 統計問題

統計問題セクション

統計データが重複しています

通知送信は少なくとも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 __CAPGO_KEEP_0__
権限が拒否されました	OSのプロンプトが拒否されましたまたはまだ要求されていません。
キューイングされましたが、送信された統計はありません	プラットフォームの資格情報が欠落していますか、または無効にされています。
送信されましたが、受信された統計はありません	デバイスがオフライン、OSがスロットル、またはアプリが強制終了、またはトークンが無効です。
フロントグラウンド通知ログがありますが、バナーはありません	アプリが前面に表示され、自身のインアプリUIを表示する必要があります。
iOSではバックグラウンドは実行されません	iOSの機能が不足している、AppDelegateのフォワーディングが不足している、強制終了されたアプリ、またはOSのサブスクリプションの制限
更新チェックは何も実行されません	アップデートの統合が無効化されています、バンドルが新しいものではありません、チャンネルが間違っています、またはインストールモードが誤解されています
バッジがリセットされます	アプリの起動時codeはバッジをクリアするか、ローカルとバックエンドのバッジの書き込みの競合を解決します

デバッグから続けてください

デバイスが登録され、テスト通知が正常に機能したら、 始め方 バッジ、キャンペーンのターゲット、静的な更新チェックをプロダクションアプリに組み込む方法を説明しています。