@capgo/capacitor-notifications

调试设置

@capgo/capacitor-notifications 连接一个 Capacitor 应用到 Capgo 的本机通知管道。您的应用程序在 Capgo 中注册一个签名的客户端用户 ID，Capgo 在 Cloudflare 分析引擎中保留最新的活跃设备状态，您可以从 Capgo 控制台或 API 发送通知、设置徽标、检查送达统计和触发静默 Capgo 实时更新检查。

该功能旨在避免在 Capgo Postgres 中创建高基数的通知设备表。Postgres 只存储低基数的控制平面数据，如应用设置、平台凭证元数据、活动草稿、计划和汇总活动记录。活跃设备状态和通知事件是只读的 Analytics Engine 行。

什么 Capgo 存储

数据	它存储在哪里	为什么
平台凭证元数据	Capgo Postgres	用于管理应用程序设置和权限。
私有平台密钥	工作者环境	避免将私密凭证存储在客户端表中。
营销活动草稿和设置	Capgo Postgres	低基数控制平面数据
已激活设备注册状态	Cloudflare 分析引擎	低成本的只读设备注册表
通知事件	Cloudflare 分析引擎	低成本的统计信息，包括排队、发送、接收、打开、失败和后台事件

身份模型

Capgo 不要求您上传用户列表或维护设备表。

• 您的后端知道真实的客户用户 ID。
• 您的后端要求 Capgo 获取一个短期的 identityProof.
• 应用程序在注册时 externalId 并且在您的用户身份验证成功后，证明。
• Capgo 为接收者和本地安装生成确定性的内部密钥。
• 发送到相同的 externalId 找到用户的活跃设备。

这使您可以在 Capgo Postgres 中查找用户的设备、设置徽章和目标通知活动ampaigns，而无需存储每个设备的通知行。

核心能力

• 使用已验证的外部用户 ID 注册设备。
• 在应用启动或令牌变化时，刷新标签、属性、同意和令牌状态。
• 在 JavaScript 中接收前台通知。
• 跟踪接收和打开通知事件。
• 处理后台数据通知。
• 设置、清除和增加应用徽章。
• 创建 Android 通知频道。
• 发送一次性通知、活动通知、徽章更新和静默更新检查。
• 触发 @capgo/capacitor-updater 从静默通知

统计

Capgo 将通知事件写入 Cloudflare 分析引擎，以便仪表板统计保持便宜：

• 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')	推送令牌发生变化时触发。

交付保证

原生推送至少一次。 一个营销活动可以重试，设备可以接收重复的消息，如果平台接受重复的消息。 使用折叠 ID 进行更新检查，并使后台工作无状态。

iOS 后台通知是最好的努力。 OS 可以根据电池、用户行为、强制退出状态和系统策略来抑制或跳过后台执行。 不要依赖静默通知来实现硬期限。

继续从@capgo/capacitor-notifications

如果您正在使用 @capgo/capacitor-notifications 来规划推送消息，连接它与 开始使用 进行设置 调试 进行故障排除 @capgo/capacitor-updater 用于静默更新检查，以及 Capgo 插件目录 {"targetLanguage":"Simplified Chinese","pagePath":"/zh/docs/plugins/notifications/","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"items":[{"text":"适用于其他本地插件。"},{"text":"编辑页面"}]}