@capgo/capacitor-notifications

概览

@capgo/capacitor-notifications 将 Capacitor 应用连接到 Capgo 的原生通知流水线。您的应用需向 Capgo 注册签名的用户 ID，Capgo 会在 Cloudflare Analytics Engine 中维护最新的活跃设备状态。您可以直接通过 Capgo dashboard 或 API 发送通知、设置角标、查看送达统计数据，并触发静默 Capgo live-update 检查。

该功能旨在避免在 Capgo Postgres 中产生高基数的通知设备表。Postgres 仅存储低基数的控制平面数据，例如应用设置、平台凭据元数据、营销活动草稿、调度计划及聚合营销记录。活跃设备状态和通知事件则以只增模式存储在 Analytics Engine 的行中。

平台支持

平台	支持	备注
iOS	是	通过 Capgo 使用 APNs
Android	是	通过 Capgo 使用 FCM
Web 端	否	单独使用 Web Push

Capgo 存储的内容

数据	存储位置	原因
平台凭据元数据	Capgo Postgres	用于管理应用配置与权限。
平台私密密钥	Worker 环境	避免将私密凭据存储在面向用户的表中。
营销活动草稿与设置	Capgo Postgres	低基数控制平面数据。
活跃设备注册状态	Cloudflare 分析引擎	低成本的仅追加式活跃设备注册表。
通知事件	Cloudflare 分析引擎	低成本统计排队、发送、接收、打开、失败及后台事件。

身份模型

Capgo 无需你上传用户列表或维护设备表。

• 你的后端已知晓真实的客户用户 ID。
• 你的后端向 Capgo 请求一个短效 identityProof.
• 应用向以下项注册 externalId 并在你自己的用户身份验证成功后提供该证明。
• Capgo 为接收者和原生安装生成确定性的内部密钥。
• 发送至同一个 externalId 再次找到用户的活跃设备。

通过此功能，您可以查询用户设备、设置角标并定向推送通知活动，而无需在 Capgo Postgres 中存储每个设备的通知记录。

核心功能

• 使用经过身份验证的外部用户 ID 注册设备。
• 在应用启动或 token 变更时，刷新标签、属性、授权状态及 token 状态。
• 在 JavaScript 中接收前台通知。
• 追踪通知的“已接收”和“已打开”事件。
• 处理后台数据通知。
• 设置、清除或递增应用角标。
• 创建 Android 通知渠道。
• 发送单次通知、营销活动通知、角标更新以及静默更新检查。
• 触发条件 @capgo/capacitor-updater 来自静默通知。

统计数据

Capgo 将通知事件写入 Cloudflare Analytics Engine，从而降低 dashboard 统计成本：

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

Stats 是运维信号，而非针对每个接收者的永久账本。由于 Analytics Engine 有数据保留策略，活跃设备必须定期刷新注册。

公开 API

方法	描述
configure	设置 Capgo app ID、API host 以及 updater 集成行为。
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')	当原生 push token 发生变化时触发。

送达保证

原生推送采用“至少一次”机制。如果平台接受重复消息，则可以重试 Campaign，设备可能会收到重复推送。请使用 collapse IDs 进行更新检查，并确保后台任务具有幂等性。

iOS 后台通知属于“尽力而为”机制。操作系统可能会根据电量、用户行为、强制退出状态和系统策略来限制或跳过后台执行。请勿依赖静默通知来处理具有严格截止时间的任务。

继续阅读 @capgo/capacitor-notifications

如果你正在使用 @capgo/capacitor-notifications 以规划推送消息，并将其与 快速入门 用于配置， 调试 排查问题， @capgo/capacitor-updater 进行静默更新检查，以及 Capgo 插件目录 用于其他原生插件。