デバッグ

GitHub

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

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

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

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

アプリを開いて、テストしたいユーザーとしてサインインしてください。
「呼び出し」 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 Logcatを開く。
アプリパッケージ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

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

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

確認してください:

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

無効なアイデンティティ証明

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のフォーカス、通知の概要、またはアプリごとの通知設定が通知を隠していません。
バッジのクリアまたはアプリを開くロジックが、配信された通知をテスト中に削除していません。

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

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

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

確認:

iOSには バックグラウンドモード > Remote notifications 有効になっている。
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 は
は呼び出された。
アプリの通知設定では、プッシュアップデートのチェックが可能です。
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 ローカルとバックエンドのバッジの送信を競合させないようにしている。

統計情報の問題

統計情報が重複している

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

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

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