调试

GitHub

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

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

从设备记录开始

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

打开应用并以您要测试的用户身份登录。
呼叫 CapgoNotifications.register(...) context: 在 Appflow 比较/迁移营销复制中看到的 Capgo UI 字符串 (父级键 `appflow_migration_step2`). 页面/区域: Appflow 比较/迁移营销复制. 角色: 网站复制句子. 见于: ionic-appflow.astro 页面. 保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `appflow_migration_step2` (Appflow 迁移步骤 2).
In Capgo 中，打开 通知 > 接收者查找.
通过相同的外部客户 ID 进行搜索。

您应该看到至少一个活动设备，显示：

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

标签和属性

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

测试期间添加临时监听器。移除在发布前产生的噪音日志。

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监听器日志。
If a visible notification does not show, inspect the notification channel importance and Android 13+ permission state first.

On iOS:

在 Xcode 中在物理设备上运行应用程序。
打开 Xcode 控制台或 设备和模拟器 过滤器
确认 CapgoNotifications.
前台测试推送一个，然后一个后台测试，然后一个静默更新检查测试。这一顺序将 JavaScript 监听器问题与 OS 背景传递限制分开。 AppDelegate.swift 注册问题

标题：注册问题

section titled

CLI 安装未完成

从包含 __CAPGO_KEEP_0__ 安装命令的文件夹中运行安装命令 capacitor.config.*:

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

如果命令无法推断您的应用 ID，请像上面所示显式传递它。如果包安装失败，请确认 Capgo 为您的 npm 帐户启用了私有预览包访问，然后重新运行命令。

设备未出现在接收者查找列表中

检查:

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焦点、通知摘要或应用程序通知设置未隐藏通知。
清除徽章或应用程序打开逻辑未在测试期间移除已投递的通知。

后台通知问题

后台回调函数未运行

背景回调不运行

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.
应用有一个更新包可供在__CAPGO_KEEP_0__中安装。 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 Debug 命令

查找接收者：

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

调试