スタートガイド

@capgo/capacitor-notifications は、iOS/Androidネイティブのプッシュ通知に対応するCapgo純正プラグインです。Capgoのダッシュボード、公開API、Analytics Engineのデバイスレジストリ、キャンペーン統計、バッジ更新、サイレントなLive Updateチェック向けに構築されています。

要件

• Capgoに既に追加済みのCapacitorアプリ。
• CapgoアプリのNotificationsタブへのアクセス権限。
• バックエンドでのproof発行とAPI送信用の、書き込み権限を持つCapgo APIキー。
• アプリのiOSおよび/またはAndroidプラットフォームにおけるプッシュ通知権限。
• @capgo/capacitor-updater サイレントプッシュでアップデートチェックを行いたい場合。

クイックスタート

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

よくある落とし穴

• バックエンドから署名済みの customerUserId を使用してください。
• 登録前に通知の許可をリクエストしてください。
• ダッシュボードで Capgo の認証情報を確認してください。

1. Capgo プラットフォームの認証情報を設定

Capgo でアプリを開き、次に以下へ移動します 通知.

サポートしたいプラットフォームごとに、1つの認証情報エントリを追加してください：

• Android - アプリのパッケージIDとAndroidプッシュプロジェクトのメタデータ。
• iOSと - bundle ID、team ID、key ID、および対応するiOSプッシュキーのメタデータ。

プラットフォームが設定済みとなる前に、API worker内に存在する必要がある環境変数の正確な名前がCapgoに表示されます。ダッシュボードにはメタデータと参照されるシークレット名のみが保存され、実際の認証情報はworker環境内に安全に保持されます。

2. インストール

最も素早くセットアップするには、アプリのプロジェクトから Capgo CLI を実行してください：

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

このコマンドは、通知パッケージのインストール、Capacitor プラグイン設定の保存、ヘルパーファイルの作成、および Capacitor sync の実行を行います。すべてのファイルを個別に手動で設定する必要がない限り、新規アプリではこのパスを使用してください。

手動インストール:

bun add @capgo/capacitor-notifications @capgo/capacitor-updater
bunx cap sync

サイレントな Capgo 更新チェックを使用していない場合は、省略できます。 @capgo/capacitor-updater.

3. プラグインの設定

アプリの起動時に一度だけプラグインを設定します。

import { CapgoNotifications } from '@capgo/capacitor-notifications'

await CapgoNotifications.configure({
  appId: 'com.example.app',
  autoUpdater: true,
  updateInstallMode: 'next',
})

使用する updateInstallMode: 'next' アップデートをダウンロードして次回の再起動時またはバックグラウンドサイクルでインストールするには、次を使用します： updateInstallMode: 'set' Capgo に、アップデータが安全に実行できるようになり次第すぐアップデートをインストールさせたい場合にのみ使用します。

4. Identity Proof の発行

Capgo API キーをモバイルアプリ内に含めないでください。独自のユーザー認証が成功した後、バックエンドから Capgo に対して identityProof リクエストを行う必要があります。

curl -X POST 'https://api.capgo.app/notifications/recipients/proof' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

取得した identityProof を、独自のセッションレスポンスと共にアプリに返してください。

5. デバイスの登録

どの顧客ユーザーがサインインしているかを確認してから、デバイスを登録してください。

const registration = await CapgoNotifications.register({
  externalId: 'customer-user-123',
  identityProof,
  tags: ['paid', 'beta'],
  attributes: {
    plan: 'team',
    locale: 'en-US',
  },
  consent: true,
})

console.log(registration.recipientKey, registration.deviceKey)

呼び出す register 以下のタイミングで再度実行します：

• アプリの起動時。
• ネイティブのプッシュトークンが変更された時。
• ログインユーザーが変更された時。
• タグ、属性、または同意設定が変更された時。
• 長期間、登録の更新が行われていない時。

6. イベントリスナーの追加

フォアグラウンド、起動時、バックグラウンドの各イベントをJavaScriptで検知できるよう、アプリの起動時にリスナーを登録してください。

await CapgoNotifications.addListener('registrationChanged', () => {
  void CapgoNotifications.register({
    externalId: currentUser.id,
    identityProof: currentUser.capgoNotificationProof,
    tags: currentUser.notificationTags,
    consent: currentUser.pushConsent,
  })
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('Notification received', notification)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('Notification opened', event.notification.id)
})

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

必ず呼び出すこと finish() 処理完了後のバックグラウンド通知用です。処理は短時間で、べき等性を保つようにしてください。

7. iOS のセットアップ

Xcodeでアプリのターゲットを開き、以下を有効にします：

• プッシュ通知
• Background Modes > Remote notifications

Remote notifications from ios/App/App/AppDelegate.swift:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name("CapgoNotificationsRemoteNotification"), object: userInfo)
    completionHandler(.newData)
}

その後、以下を実行します：

bunx cap sync ios

バックグラウンド通知のテストには実機のiOSデバイスを使用してください。シミュレーターはUI開発には便利ですが、本番環境のバックグラウンドプッシュの挙動を再現することはできません。

8. Android のセットアップ

実行:

bunx cap sync android

次に、以下を確認してください：

• Capgo に Android プラットフォームの認証情報が設定されていること。
• アプリのパッケージIDが、プラットフォームのプッシュ設定で使用したものと一致していること。
• 通知を表示させる前に、Android 13以降の通知権限のリクエストを行っていること。
• アプリに通知アイコンが設定され、ブランドに合った通知チャネル戦略が取られていること。
• 実機、または Google Play services が利用可能なエミュレータでテストしていること。

アプリ起動時に、デフォルトの Android チャネルを作成する：

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

このプラグインはAndroidのプッシュメッセージングサービスを宣言します。アプリのバックアップ、データ抽出、ネットワークセキュリティ、および通知アイコンのポリシーは、ホストアプリ側で管理してください。

9. テスト通知の送信

使用する 通知 > テスト送信 Capgo 内で、またはバックエンドから公開 API を呼び出します：

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": "Hello from Capgo",
      "body": "This is a test notification.",
      "data": { "screen": "inbox" }
    }
  }'

キャンペーンの場合は、ダッシュボードで作成するか、以下を呼び出します： /notifications/campaigns、その後、外部ID、タグ、セグメント、またはブロードキャスト対象へ送信します。

10. バッジの設定

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

バックエンド側での操作:

curl -X POST 'https://api.capgo.app/notifications/badge' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "badge": 4
  }'

11. サイレントアップデートチェックの有効化

サイレントアップデートチェックにより、このプラグインは以下と連携します： @capgo/capacitor-updater.

アプリ側での操作:

await CapgoNotifications.enableUpdaterIntegration({
  enabled: true,
  installMode: 'next',
})

Capgo で以下を有効にします： ユーザーへのアップデートのプッシュ通知 アプリの Notifications 設定にて。その後、ダッシュボードまたは API からアップデートチェックを送信してください：

curl -X POST 'https://api.capgo.app/notifications/update-check' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "installMode": "next"
  }'

通知はサイレントで、collapse IDを使用します。プラットフォームがcollapse動作をサポートしている場合、繰り返される更新チェックは互いに置き換わります。

バリデーション・チェックリスト

• Capgo の受信者検索でアプリが表示されます externalId.
• 権限は granted またはユーザーが通知権限を許可済みです。
• 登録されているプラットフォームは android または ios.
• registrationChanged トークンのリフレッシュ後に実行されます。
• フォアグラウンドでのテストログ notificationReceived.
• 通知を開くとログに記録されます notificationOpened.
• Dashboardの統計には、キューに入ったイベントと送信済みイベントが表示され、デバイスから報告されると受信/開封として表示されます。
• サイレントアップデートのチェックは、次から結果をログに記録します： runUpdateCheck またはupdater統合からです。

Getting Startedの続きを進める

セットアップがうまくいかない場合は、次を使用してください： デバッグ アプリの code を変更する前に。失敗の多くは、identity proofの不一致、プラットフォームの認証情報設定、OSの権限状態、バックグラウンドでのスロットリング、またはアプリ/パッケージIDの不一致が原因です。