快速入门

@capgo/capacitor-notifications 是原生 iOS 和 Android 推送通知的首选 Capgo 插件。它专为 Capgo 的 dashboard、公开 API、Analytics Engine 设备注册表、营销统计、Badge 更新以及静默 Live Update 检查而构建。

要求

• 已添加到 Capgo 的 Capacitor App。
• 访问 Capgo App 的 Notifications 标签页。
• 具有写入权限的 Capgo API key，用于后端证明铸造和 API 发送。
• 该 App 在 iOS 和/或 Android 平台上的推送权限。
• @capgo/capacitor-updater 如果您需要进行静默推送更新检查。

快速入门

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

常见坑点

• 使用后端签名的 customerUserId 值。
• 注册前先请求通知权限。
• 在 dashboard 中验证 Capgo 凭据。

1. 配置 Capgo 平台凭据

在 Capgo 中打开应用，然后前往 通知.

请为每个需要支持的平台添加一条平台凭据：

• Android - 应用包 ID 和 Android 推送项目元数据。
• iOS - Bundle ID、Team ID、Key ID 以及对应的 iOS 推送密钥元数据。

Capgo 会显示 API worker 中必须存在的确切环境 secret 名称，只有该 secret 存在后，平台才会被标记为已配置。Dashboard 会存储元数据和预期的 secret 引用，而私有凭据本身仍保留在 worker 环境中。

2. 安装

为了最快完成设置，请在 App 项目中运行 Capgo CLI：

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

该命令会安装通知 package、保存 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. 生成身份证明

切勿将您的 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 随您的 Session 响应一并返回给 App。

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 在以下情况再次调用：

• 应用启动时。
• 原生 push token 发生变化时。
• 登录用户发生变化时。
• 标签、属性或同意状态发生变化时。
• 应用长时间未刷新注册信息时。

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 中，打开 App target 并启用：

• 推送通知
• 后台模式 > 远程通知

从以下来源转发远程通知： 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

然后验证：

• 你的 Android 平台凭据已在 Capgo 中配置。
• App 的 package ID 与平台推送配置中使用的 package ID 一致。
• 在期望看到通知之前，已请求 Android 13+ 的通知权限。
• App 的通知图标和渠道策略与你的品牌一致。
• 你在真机或带 Google Play services 的模拟器上测试。

在 App 启动时创建一个默认的 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" }
    }
  }'

对于营销活动，请在 dashboard 中创建，或调用 /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.

在 App 中：

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

在 Capgo 中，启用 向用户推送更新 在 App 的 Notifications 设置中。然后通过 dashboard 或 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。在平台支持折叠行为时，重复的更新检查会相互替换。

验证清单

• App 出现在 Capgo 接收者查询中，符合预期 externalId.
• 权限为 granted 或者用户已接受通知权限。
• 注册的平台是 android 或 ios.
• registrationChanged 在 token 刷新后触发。
• 前台测试日志 notificationReceived.
• 查看通知打开日志 notificationOpened.
• Dashboard 统计会显示排队和已发送的事件，并在设备上报时显示已接收/已打开。
• 静默更新检查会记录来自 runUpdateCheck 或 updater 集成的结果。

从入门指南继续

如果配置无法工作，请使用 调试 在更改应用 code 之前。大多数失败是由身份验证不匹配、平台凭据设置、OS 权限状态、后台限制或应用/包 ID 不匹配引起的。