@capgo/capacitor-通知

概述

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

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

Capgo 存储什么

数据	存储在哪里	为什么
平台凭证元数据	Capgo PostgreSQL	用于管理应用程序设置和权限。
私有平台密钥	工作环境	避免将私有凭证存储在客户端表中。
营销活动草稿和设置	Capgo PostgreSQL	低基数控制平面数据。
活跃设备注册状态	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

统计是操作指标，而不是永久的个人记录。分析引擎的保留意味着活跃设备必须定期刷新注册。

公共 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 后台通知是尽力而为的。 操作系统可以根据电池、用户行为、强制退出状态和系统政策来抑制或跳过后台执行。 不要依赖静默通知来实现硬期限。

继续从 @capgo/capacitor-notifications

如果您正在使用 @capgo/capacitor-通知 来规划推送消息，请将其连接到 开始 进行设置 调试 用于排错 @capgo/capacitor-更新器 context Capgo 插件目录 用于静默更新检查，和