调试

GitHub

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

在通知未注册、未到达、未显示或未更新 Capgo 统计时，请使用此清单。

从设备记录开始

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

打开应用并以您要测试的用户身份登录。
Call CapgoNotifications.register(...) context
在Capgo中，打开 在 __CAPGO_KEEP_0__ 中打开 ‘通知 > 接收者查找’.
根据相同的外部客户ID进行搜索。

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

recipientKey
deviceKey
平台 android 或 ios
在Capacitor live-update替代方案比较页面中，查看Capacitor替代方案的市场或法律段落。
应用版本
在Capawesome比较页面中，查看Capawesome比较。
在咨询服务页面中，查看Capgo咨询服务。

在Appflow比较/迁移市场复制页面中，查看Appflow插件或。

权限状态

插件版本号码

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 来自注册或查找接收者。
【Campaign ID 或通知 ID】
【应用是否在前台、后台、强制关闭或刚刚安装】
【设备日志，来自导致问题的运行】

【使用设备日志】

【在测试通知时，请保持一个真实设备连接】

【在 Android 上：】

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

【在 iOS 上：】

在 Xcode 中在物理设备上运行应用程序。
打开 Xcode 控制台或 设备和模拟器 日志。
根据包 ID 过滤并 CapgoNotifications.
确认 AppDelegate.swift 前台测试推送通知并确保后台模式能力已启用。

发送一个前台测试，然后一个后台测试，然后一个静默更新检查测试。这一顺序将 JavaScript 监听器问题与 OS 后台传递限制分开。

注册问题

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 in configure 匹配的Capgo应用
consent 没有设置为 false 除非用户已选择退出。
设备有网络访问到 https://api.capgo.app.
本地推送令牌已创建。使用 registrationChanged 确认令牌刷新

无效身份证明

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

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

设备已注册但权限被拒绝

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

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

投递问题

排队但未发送

检查：

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

已发送但未接收

检查：

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

Native push 平台可以接受通知并延迟、限制、合并或丢弃后续传递。将提供商接受的统计数据视为“已交付”，而不是设备已显示它的证据。

未显示的接收

检查：

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

背景通知问题

背景回调函数未运行

背景回调不运行

Check:

检查： iOS有 背景模式>远程通知
已启用。 AppDelegate.swift iOS CapgoNotificationsRemoteNotification.
将远程通知转发给
您在物理设备上测试iOS背景行为。
应用程序未被用户强制退出。 finish().
后台处理程序调用了‘background’回调函数：

在 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.
应用有一个更新包可供在__CAPGO_KEEP_0__中安装。 next 您的更新安装模式是正确的： set 在下一次重启或后台循环时排队等待

尽快安装， updater 可以安全地进行安装。

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

console.log(result)

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

徽章问题

检查:

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

统计问题

统计数据重复

通知发送至少一次。队列重试和平台重试可以重复发送。使用通知 ID 和折叠 ID，当您的应用程序操作必须幂等时。

老设备统计数据缺失

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

打开事件缺失

检查：

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

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

调试