@capgo/capacitor-通知

概述

@capgo/capacitor-notifications 连接一个 Capacitor 应用程序到 Capgo 的本机通知管道。您的应用程序注册一个签名的客户端用户 ID 与 Capgo, 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 中存储每个设备的通知行。

核心能力

• 在已验证外部用户 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')	触发时native推送令牌发生变化。

交付保证

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

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

继续从 @capgo/capacitor 通知中继续

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