调试

GitHub

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

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

从设备记录开始

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

打开应用并以您要测试的用户身份登录。
在登录后调用。 CapgoNotifications.register(...) 在 __CAPGO_KEEP_0__ 中打开
In Capgo, open 通过相同的外部客户 ID 进行搜索。.
Ready to paste

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

recipientKey
deviceKey
__CAPGO_KEEP_0__ android 或 ios
权限状态
应用程序版本
插件版本
标签和属性

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

添加临时调试监听器

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

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 监听器问题与 OS 后台传递限制分开。

注册问题

CLI 设置未完成

的文件夹运行 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 unless the user opted out.
设备有网络访问权限到 https://api.capgo.app.
native push token 已创建。使用 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，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 应用的通知设置允许推送更新检查。
您期望的频道中设备属于目标设备。
应用有一个在__CAPGO_KEEP_0__中可用的更新包。
The app has a newer bundle available in Capgo.
在下一次重启或后台循环中排队 next 在安全的时间安装： set 在应用打开时运行一次手动检查：

复制到剪贴板

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

console.log(result)

首先检查更新插件的设置。 unavailableCopy to clipboard

Badge 问题

检查：

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

统计问题

统计数据重复

通知发送至少会重试一次。队列重试和平台重试可能会导致重复发送。请在应用程序操作必须幂等时使用通知 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` __CAPGO_KEEP_0__
无权限	操作系统提示未被请求或被拒绝
排队但未发送统计	平台凭证丢失或被禁用
已发送但未接收统计	设备离线、操作系统限制、应用程序被强制停止或令牌无效
前台通知日志但无横幅	应用程序位于前台，必须显示其自己的内应用程序 UI。
iOS 中的背景永远不会运行	缺少功能，缺少 AppDelegate 转发，强制退出应用程序，或者操作系统的限制
更新检查什么都没有做	Updater 集成已禁用，没有更新的包，错误的频道，或者安装模式被误解
徽标重置	应用程序启动时 code 清除徽标或本地和后端徽标写入的竞争

继续 Debugging

设备注册并且测试通知成功后，使用 Getting Started 来将徽标，推广目标，和静默更新检查集成到您的生产应用程序中