调试

GitHub

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

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

从设备记录开始

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

打开应用并以您要测试的用户身份登录。
调用 CapgoNotifications.register(...) context:HTML 文本片段来自更长的 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监听器日志。
如果一个可见的通知没有显示出来，请先检查通知通道的重要性和 Android 13+ 权限状态。

在 iOS 上：

在 Xcode 中在物理设备上运行应用程序。
打开 Xcode 控制台或 设备和模拟器 日志。
通过应用程序 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 页面/区域：Capgo营销网站。角色：短 UI 标签或导航项。见于：页面trust.astro。消息键 `and` (And)。 configure matches the Capgo app.
consent 匹配的__CAPGO_KEEP_0__应用。 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没有 finish().

，JavaScript 处理程序很可能会抛出异常、超时或未调用 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 立即安装一旦更新器可以安全地执行。

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

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

console.log(result)

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

徽章问题

检查：

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

统计问题

统计数据重复

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

老设备的统计数据缺失

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

打开事件缺失

检查:

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

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

调试