@capgo/capacitor-notifications

概要

@capgo/capacitor-notifications Capacitor アプリを Capgo のネイティブ通知パイプラインに接続します。アプリが署名付きの顧客ユーザーIDを Capgo に登録すると、Capgo が最新のアクティブなデバイス状態を Cloudflare Analytics Engine に保持します。Capgo ダッシュボードまたは API から、通知の送信、バッジ設定、配信統計の確認、Capgo のサイレント live-update チェックの実行ができます。

この機能は、Capgo の Postgres で高カーディナリティな通知デバイステーブルを避けるように設計されています。Postgres に保存されるのは、アプリ設定、プラットフォーム認証情報のメタデータ、キャンペーンの下書き、スケジュール、キャンペーンの集計レコードなど、低カーディナリティなコントロールプレーンデータのみです。アクティブなデバイス状態と通知イベントは、Analytics Engine の append-only 行です。

プラットフォーム対応

プラットフォーム	サポート	備考
iOSと	はい	Capgo 経由の APNs
Android	はい	Capgo を使用した FCM
Web	いいえ	Web Push は別途利用

Capgo の保存内容

データ	保存場所	理由
プラットフォームの認証情報メタデータ	Capgo Postgres	アプリの設定や権限の管理に必要です。
プラットフォームのプライベートシークレット	Worker環境	顧客向けのテーブルにプライベートな認証情報を保存するのを避けます。
キャンペーンの下書きと設定	Capgo Postgres	低カーディナリティのコントロールプレーンデータ。
アクティブなデバイスの登録状態	Cloudflare Analytics Engine	低コストな追記専用のアクティブデバイスレジストリ。
通知イベント	Cloudflare Analytics Engine	キュー、送信、受信、開封、失敗、バックグラウンドイベントの統計を低コストで取得。

Identity Model

Capgo では、ユーザーリストのアップロードやデバイステーブルの管理は不要です。

• 実際の顧客ユーザーIDは、バックエンド側で管理されます。
• バックエンドから Capgo へ短期間有効な identityProof.
• アプリが以下で登録を行います： externalId 独自のユーザー認証が成功した後に、その証明を渡します。
• Capgo は、受信者とネイティブインストールに対して決定論的な内部キーを生成します。
• 同じ対象へ送信する場合、 externalId ユーザーのアクティブなデバイスを再度特定します。

Capgo Postgres にデバイスごとの通知レコードを保存することなく、ユーザーのデバイス検索、バッジの設定、通知キャンペーンのターゲット指定が可能です。

コア機能

• 認証済みの外部ユーザーIDを使用してデバイスを登録します。
• アプリ起動時やトークン変更時に、タグ、属性、同意、トークンの状態を更新します。
• フォアグラウンドでの通知を JavaScript で受信します。
• 通知の受信および開封イベントをトラッキングします。
• バックグラウンドでのデータ通知を処理します。
• アプリのバッジの設定、クリア、インクリメントを行います。
• Android の通知チャンネルを作成します。
• 単発の通知、キャンペーン通知、バッジの更新、サイレントな更新チェックを送信します。
• トリガー @capgo/capacitor-updater サイレント通知から。

統計

Capgo は通知イベントを Cloudflare Analytics Engine に書き込むため、ダッシュボードの統計を低コストに保てます：

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

統計は運用上のシグナルであり、受信者ごとの永続的な台帳ではありません。Analytics Engine の保持期間の関係上、アクティブなデバイスは定期的に登録を更新する必要があります。

公開 API

メソッド	説明
configure	Capgo のアプリID、API のホスト、およびアップデーター統合の動作を設定します。
register	現在のインストールを外部の顧客ユーザーIDに紐付けます。
setExternalId	ログイン後やアカウント切り替え後に、外部の顧客ユーザーIDを変更します。
setTags	オーディエンスターゲティングに使用するタグを置換します。
setBadge	ネイティブアプリのバッジを設定します。
clearBadge	ネイティブアプリのバッジをクリアします。
incrementBadge	ネイティブアプリのバッジをインクリメントします。
enableUpdaterIntegration	〜を通じてサイレントアップデートチェック処理を有効にします @capgo/capacitor-updater.
runUpdateCheck	テスト用にアップデーター統合を手動で実行します。
trackReceived	受信イベントを手動で書き込みます。
trackOpened	開封イベントを手動で書き込みます。
addListener('notificationReceived')	JavaScriptがアクティブな状態で通知を受信したときに発火します。
addListener('notificationOpened')	ユーザーが通知を開いたときに発火します。
addListener('backgroundNotification')	バックグラウンドデータ通知で発火し、〜を公開します finish().
addListener('registrationChanged')	ネイティブのプッシュトークンが変更されたときに発火します。

配信の保証について

ネイティブプッシュは「少なくとも1回（at-least-once）」の配信を保証します。プラットフォームが重複メッセージを受け付けた場合、キャンペーンの再試行によりデバイスに重複して届く可能性があります。更新チェックには collapse ID を使用し、バックグラウンド処理は冪等（idempotent）に設計してください。

iOSのバックグラウンド通知は「ベストエフォート」です。バッテリー残量、ユーザーの行動、アプリの強制終了状態、システムポリシーに基づき、OSがバックグラウンド実行を制限またはスキップすることがあります。厳密な期限が必要な処理にサイレント通知を使用しないでください。

@capgo/capacitor-notifications から先に進む

使用している場合 @capgo/capacitor-notifications プッシュメッセージングの計画を立てるには、以下と連携させてください スタートガイド セットアップ用、 デバッグ トラブルシューティング用、 @capgo/capacitor-updater サイレントアップデート確認用、および Capgo プラグインディレクトリ その他のネイティブプラグイン用。