调试

GitHub

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

在通知未注册、未收到、未显示或未更新 Capgo 统计时，请使用此检查表。

从设备记录开始

在调试原生 code 之前，请确认 Capgo 可以看到设备。

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

您应该看到至少一个活动设备有：

recipientKey
deviceKey
平台 android 或 ios
您可以在 __CAPGO_KEEP_0__ 中看到更多关于 __CAPGO_KEEP_1__ 的信息。
权限状态
应用程序版本
插件版本

标签和属性

如果查找返回没有设备，则发送路径无法针对该用户。

测试时添加临时监听器，发布前清除杂音日志

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 控制台或 设备和模拟器 日志。
根据应用程序 ID 过滤日志并 CapgoNotifications.
确认 AppDelegate.swift 远程通知可以正常接收并且后台模式能力已启用。

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

注册问题

CLI Setup Did Not Finish

__CAPGO_KEEP_0__ Setup Did Not Finish capacitor.config.*:

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

If the command cannot infer your app ID, pass it explicitly as shown above. If package installation fails, confirm Capgo has enabled private-preview package access for your npm account, then rerun the command.

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

检查：

register 是否在应用启动后调用了认证用户的方法。
externalId 是否匹配了您在控制台中搜索的用户 ID。
identityProof 是否由您的后端为同一个用户 ID minted。 appId 和 externalId.
appId 在 configure 匹配的应用程序是 Capgo。
consent 没有设置为 false 除非用户放弃
设备有网络访问权 https://api.capgo.app.
本地推送令牌已创建。使用 registrationChanged 确认令牌刷新

无效身份证明

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

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

设备已注册但权限被拒绝

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

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

传递问题

排队但未发送

检查：

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

已发送但未接收

检查：

设备在线。
用户没有强制停止应用程序。
操作系统通知权限已授权。
在测试期间，Android 电池限制不会阻止应用程序。
iOS 低功耗模式和背景刷新限制不会影响背景传递。
通知没有被具有相同的折叠 ID 的另一个通知替换。

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

未显示的接收

检查：

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

背景通知问题

背景回调函数未运行

背景回调不运行

Check:

检查: iOS has iOS已启用
Background Modes > Remote notifications AppDelegate.swift 背景模式 > 远程通知 CapgoNotificationsRemoteNotification.
iOS
iOS
forwards remote notifications to 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 您正在使用的更新安装模式是正确的：
在下一次重启或后台循环时排队等待
一旦更新器可以安全地安装它，它就会立即安装。
The app has a newer bundle available in Capgo.
应用程序的通知设置允许推送更新检查。 next 目标设备属于您期望的频道。 set 应用程序有一个更新包可供您在__CAPGO_KEEP_0__中安装。

应用程序曾被称为。

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 Debug Commands

查找接收者：

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清除徽标或本地和后端徽标写入竞争

调试