调试

GitHub

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

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

从设备记录开始

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

打开应用并以您要测试的用户身份登录。
呼叫 CapgoNotifications.register(...) 在登录后呼叫。
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 Setup Did Not Finish

从包含__CAPGO_KEEP_0__的文件夹中运行设置命令 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.

设备已注册但权限被拒绝

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

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

投递问题

检查：

__CAPGO_KEEP_0__

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

已发送但未接收

检查：

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

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

未显示的收到

检查：

应用程序没有置顶。置顶通知通常会将推送交给 JavaScript，以便应用程序可以决定显示哪些 UI。
Android 通知频道重要性足够高以显示警告。
Android 13+ 通知权限已授予。
iOS 焦点、通知摘要或应用程序通知设置不会隐藏通知。
徽章清除或应用程序打开逻辑不会在测试期间移除已交付的通知。

后台推送问题

后台回调函数未运行

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

检查：

iOS 有 后台模式 > 远程通知 已启用。
iOS AppDelegate.swift 将远程通知转发给 CapgoNotificationsRemoteNotification.
您在物理设备上测试 iOS 后台行为。
应用程序未被用户强制退出。
The background handler calls 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 您正在使用Capacitor的live-update替代方案进行比较。
或
应用程序的通知设置允许推送更新检查。
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首先检查更新插件设置。

徽章问题

检查：

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

统计问题

重复的统计

通知发送至少会进行一次。队列重试和平台重试可能会导致重复发送。请使用通知 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"
  }'