调试

GitHub

复制安装、同步和完整指南的配置提示

使用此清单检查通知未注册、未收到、未显示或未更新Capgo统计数据时。

从设备记录开始

在调试本机code之前，确认Capgo可以看到设备。

打开应用程序并以您要测试的用户身份登录。
调用 CapgoNotifications.register(...) context
在Capgo中，打开 登录后.
在__CAPGO_KEEP_0__中打开

通知>收件人查找

recipientKey
deviceKey
通过相同的外部客户ID进行搜索。 android 或 ios
权限状态
应用版本
插件版本
标签和属性

如果查找设备失败，无法为该用户设置目标路径。

添加临时调试监听器

测试时添加临时监听器。移除干扰日志前发布。

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应用ID。
应用包ID或iOS包ID。
设备平台和OS版本。
应用版本和构建号。
插件版本。
外部客户ID。
recipientKey 和 deviceKey 从注册或接收者查找。
活动ID或通知ID。
应用是否在前台、后台、强制关闭或刚刚安装。
设备日志从导致问题的运行中获取。

使用设备日志

确保在发送测试通知时始终连接一个真实设备。

在 Android 上：

在 Android Studio 中打开 Logcat。
过滤应用包 ID。
查看通知权限请求、原生令牌刷新、消息接收和 JavaScript 监听器日志。
如果可见通知未显示，请先检查通知渠道重要性和 Android 13+ 权限状态。

在 iOS 上：

在 Xcode 中在物理设备上运行应用。
打开 Xcode 控制台或 设备和模拟器 日志。
根据 bundle ID 过滤 CapgoNotifications.
确认 AppDelegate.swift 前台推送和后台推送功能都正常工作，且后台模式能力已启用。

先发送一个前台测试，然后一个后台测试，然后一个静默更新检查测试。这种顺序可以分离 JavaScript 监听器问题和操作系统后台传递限制。

注册问题

CLI 设置未完成

从包含该文件夹的设置命令的终端窗口中运行 capacitor.config.*:

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

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

设备未在接收者查找列表中显示

检查：

register 在您的应用程序有经过身份验证的用户后
externalId 匹配您在控制台中搜索的用户 ID
identityProof 由您的后端为相同的 appId 和 externalId.
appId 在 configure 匹配您的 Capgo 应用程序
consent 没有设置为 false 除非用户选择退出。
设备有网络访问权 https://api.capgo.app.
创建了本机推送令牌。使用 registrationChanged 确认令牌刷新

无效身份证明

该证明绑定到Capgo应用ID和外部ID。如果其中一个值发生变化，请生成新的证明。

不要将一份证明永久缓存或在多个应用之间重用。从您的后端登录后生成它，返回给应用，然后调用 register.

设备已注册但权限被拒绝

即使用户拒绝权限，插件也可以注册设备状态。您仍然可以看到设备，但可见通知不会显示。

在操作前，使用权限提示屏幕。解释用户将获得什么，然后在操作有意义时才要求权限。

送达问题

排队但未发送

检查：

平台凭证状态是 configured Capgo。
工作环境包含由控制台显示的精确密钥引用。
应用程序中的包 ID 或捆绑 ID 与平台推送设置匹配。
目标受众至少有一个活跃设备。
广告不仅限于设备没有的标签或分段。

已发送但未接收

检查：

设备在线。
用户未强制停止应用。
已获得操作系统通知权限。
安卓测试期间，设备的电池限制不阻止应用。
iOS低功耗模式和后台刷新限制不影响后台推送。
通知未被另一个具有相同折叠 ID 的通知替换。

本机推送平台可以接受通知并延迟、限制、合并或丢弃后续的推送。请将提供者接受的统计数据视为“已交付”，而不是设备已显示它的证明。

已接收但未显示

检查：

应用程序未置于前台。通常，前台通知会传递给JavaScript，以便应用程序可以决定显示哪些UI。
Android通知渠道重要性足够高，以显示警告。
Android 13+通知权限已被授予。
iOS聚焦、通知摘要或应用程序通知设置未隐藏通知。
清除应用程序图标或打开应用程序逻辑未在测试期间移除已传递的通知。

背景通知问题

背景回调函数未运行

背景通知是最好努力的。操作系统可以跳过它们。

检查：

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 曾被称为
应用的通知设置允许推送更新检查
目标设备属于您期望的频道
应用有一个更新的捆绑包可在Capgo中找到
您的更新安装模式是正确的： next 在下一次重启或后台循环之前排队 set 尽可能安全地安装

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

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

console.log(result)

如果手动检查返回 unavailable,请先检查更新插件的设置

徽章问题

检查：

目标在接收者查找中解析到正确的设备。
该平台支持用于测试的启动器或主屏幕的应用徽章。
用户没有在操作系统通知设置中禁用徽章。
应用程序在启动时不立即清除徽章。
您不在本地 setBadge 调用与后端徽章发送相竞争。

统计问题

统计看起来是重复的

至少一次发送通知。队列重试和平台重试可能导致重复发送。使用通知 ID 和折叠 ID 来确保您的应用程序操作是幂等的。

旧设备统计数据缺失

分析引擎注册表是为活跃设备准备的，而不是永久数据库。插件应该在应用程序启动、令牌刷新、外部 ID 变更和活跃设备保留期前周期性刷新注册。

打开事件缺失

检查：

通知包含一个稳定的 id.
notificationOpened 监听器在应用程序启动时注册。
The app is not replacing the native open flow with custom code before the plugin sees it.
用户实际上点击了通知而不是手动打开应用程序。

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` 未被调用，证据不符，同意未通过，应用ID不符。
权限被拒绝	操作系统提示未被允许或尚未请求。
排队但未发送统计	平台凭证丢失或已禁用。
已发送但未接收统计	设备离线，操作系统限制，应用强制停止，或者令牌无效。
前台通知日志但无横幅	应用程序位于前台，必须显示其自己的内嵌 UI。
iOS 中的后台永远不会运行。	缺少能力、AppDelegate 转发缺失、强制退出应用程序或操作系统限制。
更新检查什么都没有做。	更新器集成已禁用、无新包、错误的频道或安装模式被误解。
标签重置。	应用程序启动时 code 清除标签或本地和后端标签写入的竞争。

调试