开始使用

@capgo/capacitor-notifications is the first-party Capgo plugin for native iOS and Android push notifications. It is built for Capgo’s dashboard, public API, Analytics Engine device registry, campaign stats, badge updates, and silent live-update checks.

需求

• 一个Capacitor已经添加到Capgo。
• 访问 Capgo 应用程序的通知选项卡。
• 一个 Capgo API 密钥，具有写入访问权限，以便在后端进行证明铸造和 API 发送。
• 应用程序的 iOS 和/或 Android 平台推送权限。
• @capgo/capacitor-updater 如果您想进行静默推送更新检查。

1. 配置Capgo 平台凭证

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

添加每个平台的凭证项：

• Android - 应用包 ID 和 Android 推送项目元数据。
• iOS - 应用程序 ID、团队 ID、密钥 ID 和匹配的 iOS 推送密钥元数据。

Capgo 显示必须在API 工作人员中存在的精确环境密钥名称。工作台存储元数据和预期密钥引用。私密凭证本身留在工作人员环境中。

2. 安装

快速设置，请在您的应用项目中运行 Capgo CLI。

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

The command installs the notification package, saves the Capacitor plugin config, creates a small helper file, and runs Capacitor sync. Use this path for new apps unless you need to wire every file manually.

The command installs the notification package, saves the __CAPGO_KEEP_0__ plugin config, creates a small helper file, and runs __CAPGO_KEEP_1__ sync. Use this path for new apps unless you need to wire every file manually.

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

如果您不使用静默Capgo更新检查，则可以省略 @capgo/capacitor-updater.

If you are not using silent __CAPGO_KEEP_0__ update checks, you can omit

标题：3. 配置插件

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

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

使用 updateInstallMode: 'next' 下载更新并在下次重启或后台循环中安装它。使用 updateInstallMode: 'set' 仅在您希望 Capgo 立即在安全时机安装更新时使用。

4. mint一个身份证明

不要将您的 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)

Call register 呼叫

• 上下文：Appflow比较/迁移营销复制。页面/区域：页面alternatives/ionic-appflow.astro。角色：网站复制句子。保留Capgo产品/品牌和开发者术语完全不变。消息键`appflow_migration_step2`（Appflow迁移步骤2）。
• 当：
• 应用程序启动时。
• 原生推送令牌发生变化时。
• 已登录用户发生变化时。

标签、属性或同意发生变化时。

在应用启动时注册监听器，以便 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 中，打开应用目标并启用：

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

将远程通知从 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. 安卓设置

运行：

bunx cap sync android

然后验证：

• 您的安卓平台凭据已在Capgo中配置。
• 应用程序包ID与用于平台推送设置的包ID匹配。
• 在安卓13+之前，请求可见通知权限。
• 应用程序有一个通知图标和与品牌匹配的通道策略。
• 您可以在物理设备或模拟器上测试，使用Google Play服务。

当应用程序启动时，创建一个默认的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()

背景：Capgo营销网站。角色：UI标签。位置：页面代理/[slug].astro。消息键 `agents_page_copy_label` (代理页面复制标签)。

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中启用 推送更新给用户 在应用的通知设置中启用，然后从控制台或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"
  }'

该通知是静默的，并使用折叠 ID，因此当平台支持折叠行为时，重复的更新检查将互相替换。

验证清单

• 应用程序将出现在Capgo的接收者查找中，用于预期的 externalId.
• 权限已获得 granted 或用户已接受通知权限。
• 已注册的平台是 android 或 ios.
• registrationChanged 刷新令牌后触发
• 前台测试日志 notificationReceived.
• 打开通知日志 notificationOpened.
• 仪表板统计显示排队和发送的事件，然后在设备报告它们时接收/打开
• 静默更新检查记录来自 runUpdateCheck 或更新器集成

继续从开始

如果设置不起作用，请使用 调试 在更改应用程序 code 之前。最常见的失败原因是身份证明不匹配、平台凭证设置、操作系统权限状态、后台节流或应用程序/包 ID 不匹配。