调试

GitHub

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

如果通知未注册、未送达、未显示或未更新 Capgo 统计数据，请参考此检查清单。

从设备记录开始排查

在调试原生 code 之前，请确认 Capgo 可以识别该设备。

打开 App 并以你要测试的用户身份登录。
调用 CapgoNotifications.register(...) 登录后。
在 Capgo 中，打开 通知 > 收件人查询.
使用相同的外部客户 ID 进行搜索。

你应该至少能看到一个处于活跃状态的设备，其信息如下：

recipientKey
deviceKey
platform android 或 ios
权限状态
App 版本
插件版本
标签与属性

如果查询未返回设备，则发送路径无法指向该用户。

添加临时调试监听器

测试期间添加临时监听器。发布前请移除冗余日志。

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

收集这些信息

在与团队或 Capgo 支持团队协作调试时，请收集：

Capgo App ID。
App 包名 (Package ID) 或 iOS bundle ID。
设备平台及 OS 版本。
App 版本号与 build number。
Plugin 版本。
外部客户 ID。
recipientKey 以及 deviceKey 通过注册或收件人查询获取。
Campaign ID 或 notification ID。
App 状态：前台、后台、强杀或全新安装。
复现问题时的设备 logs。

使用设备日志

发送测试通知时，请保持一台真机处于连接状态。

在 Android 上：

打开 Android Studio Logcat。
通过应用包名 (package ID) 进行过滤。
重点关注通知权限请求、native token 刷新、消息接收以及 JavaScript listener 的相关日志。
如果未显示可见通知，请先检查通知渠道 (notification channel) 的重要性级别以及 Android 13+ 的权限状态。

在 iOS 上：

通过 Xcode 在真机上运行应用。
打开 Xcode 控制台，或 设备与模拟器 日志。
通过 bundle ID 进行筛选，并且 CapgoNotifications.
确认 AppDelegate.swift 转发远程通知，并确保已启用后台模式 (background mode) 能力。

先发送一个前台测试，接着一个后台测试，最后进行一次静默更新检查测试。这种顺序可以将 JavaScript 监听器问题与操作系统的后台推送限制区分开来。

注册问题

CLI 配置未完成

在包含以下内容的文件夹中运行 setup 命令 capacitor.config.*:

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

如果命令无法推断您的 App ID，请按上述方式显式传递。如果安装包失败，请确认包名是否 @capgo/capacitor-notifications，验证您的 npm 注册表是否 https://registry.npmjs.org，检查网络访问权限，然后重新运行命令。

收件人查询中未找到设备

检查：

register 是在您的 App 已有已认证用户后调用的。
externalId 与您在 dashboard 中搜索的用户 ID 一致。
identityProof 是由您的后端为同一个 appId 以及 externalId.
appId 中的 configure 与 Capgo App 匹配。
consent 未设置为 false 除非用户选择了退出。
设备已连接至网络的 https://api.capgo.app.
原生 push token 已创建。请使用 registrationChanged 来确认 token 是否刷新。

身份凭证无效

该 proof 与 Capgo app ID 及外部 ID 绑定。如果其中任何一个值发生变化，请重新 mint 一个新的 proof。

请勿永久缓存某个 proof，也不要在不同 app 之间复用。请在登录后从你的后端 mint 它，将其返回给 app，然后调用 register.

设备已注册但权限被拒绝

即使用户拒绝了权限，该 plugin 仍能注册设备状态。你仍然可以看到该设备，但不会显示可见的通知。

在系统权限弹窗出现前，先使用自定义的权限引导页。向用户解释权限用途，并在操作逻辑合理时再请求权限。

送达问题

已进入队列但未发送

检查：

平台凭据状态为 configured 在 Capgo 中。
Worker 环境中包含与 dashboard 显示完全一致的 Secret 引用。
App 中的 Package ID 或 Bundle ID 与平台的推送配置一致。
目标受众至少包含一台活跃设备。
该 Campaign 未被限制在设备不具备的 Tag 或 Segment 内。

已发送但未收到

检查：

设备处于在线状态。
用户未强制停止应用。
已授予系统的通知权限。
测试期间 Android 电池限制未拦截应用。
iOS 低电量模式和后台刷新限制未影响后台推送。
该通知未被具有相同 collapse ID 的其他通知覆盖。

原生推送平台在接收通知后，仍可能延迟、节流、合并或丢弃推送。请将服务商的“已接受”统计视为“已接受推送”，而非设备已展示通知的证明。

已收到但未显示

检查：

应用未处于前台。前台通知通常会传给 JavaScript，让应用决定显示什么 UI。
Android 通知渠道的重要性足够高，可以显示提醒。
已授予 Android 13+ 的通知权限。
iOS 的专注模式、通知摘要或单个 App 的通知设置没有隐藏该通知。
测试期间，清除 Badge 或应用打开逻辑不会移除已送达的通知。

后台通知问题

后台回调未运行

后台通知属于尽力而为（best-effort）机制。操作系统可能会跳过它们。

检查：

iOS 已 后台模式 > 远程通知 启用。
iOS AppDelegate.swift 将远程通知转发至 CapgoNotificationsRemoteNotification.
请在真机上测试 iOS 的后台行为。
用户未强制退出应用。
后台处理器调用 finish().
回调函数中的工作应保持简短、网络安全且具备幂等性。

在 iOS 上，如果您发送过多推送、耗时过长或用户很少打开应用，后台推送可能会被限流。这是平台的预期行为。

后台已启动但未完成

如果统计数据表明 background_started 无需 background_finished，则 JavaScript 处理程序可能抛出了异常、超时或未调用 finish().

将处理程序包装在 try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

静默更新检查问题

收到更新检查通知但未安装更新

检查：

@capgo/capacitor-updater 已安装并配置完成。
autoUpdater 为 true 或 enableUpdaterIntegration 已被调用。
应用的 Notifications 设置允许进行推送更新检查。
目标设备属于你预期的 channel。
应用在 Capgo 中有更新的 bundle 可用。
你的更新安装模式配置正确： next 在下次重启或后台周期时排队， set 在 updater 可以安全执行时立即安装。

在应用打开时运行手动检查：

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

如果手动检查返回 unavailable，请先检查 updater plugin 的配置。

Badge 问题

检查：

接收者查询时，目标已正确解析到对应的设备。
当前测试的启动器或主屏幕支持平台 App Badge。
用户未在系统通知设置中禁用 Badge。
App 在启动时未立即清除 Badge。
本地调用与后端 setBadge Badge 发送请求之间存在竞态条件。

Stats 问题

Stats 看起来重复了

通知发送采用“至少一次”机制。队列重试和平台重试可能会导致重复发送。如果您的应用操作必须满足幂等性，请使用 notification IDs 和 collapse IDs。

旧设备缺少统计数据

Analytics Engine 注册表是针对活跃设备的，而非永久数据库。插件应在应用启动、token 刷新、外部 ID 变更时，以及活跃设备保留窗口到期前定期刷新注册。

缺少 Open 事件

检查：

通知中包含一个稳定的 id.
notificationOpened 监听器在应用启动时注册。
在插件捕获到事件之前，应用没有用自定义的 code 替换原生的 open 流程。
用户实际上是点击了通知，而不是手动打开应用。

API 调试命令

查询接收者：

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

读取统计数据：

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

发送前台测试：

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": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

常见根本原因

现象	可能原因
查询中未找到设备	`register` 未调用、证明不匹配、拒绝授权或 App ID 不匹配。
权限被拒绝	OS prompt 已拒绝或尚未请求权限。
已进入队列但无发送统计	平台凭据缺失或已禁用。
已发送但无接收统计	设备离线、OS 节流、App 被强制停止或 token 无效。
有前台通知日志但无横幅显示	应用处于前台，必须显示其自身的应用内 UI。
iOS 上从不运行后台任务	缺少 Capabilities、AppDelegate 转发缺失、应用被强制退出或系统限制。
检查更新无响应	Updater 集成已禁用、没有更新的 bundle、Channel 错误或对安装模式理解有误。
Badge 被重置	应用启动 code 清除了 Badge，或本地与后端 Badge 写入存在竞态条件。

调试