极光推送_推送排查

推送排查最佳实践

推送排查的关键不是只看“用户有没有收到”，而是把一次推送拆成可验证的链路：请求是否成功、目标是否命中、通道是否可用、消息是否被厂商接收、设备是否展示、用户是否点击。每一层都有对应的排查工具和数据口径。

本文适用于通知消息、自定义消息、Android 厂商通道、iOS APNs、HarmonyOS 通道以及通过 API 或控制台创建的推送任务。

排查前先准备信息

定位单个设备问题时，建议先准备以下信息：

AppKey：确认排查的应用与推送请求使用的是同一个 AppKey。
Message ID：控制台推送可在推送记录中查看；API 推送可从接口返回的 msg_id 获取。
Registration ID：客户端初始化成功后获取，排查单设备问题时必须使用目标设备当前有效的 Registration ID。
推送请求体：尤其是 platform、audience、notification、message、options、third_party_channel 等字段。
设备环境：系统类型、系统版本、机型、App 版本、SDK 版本、通知权限、网络状态、是否卸载重装。
业务期望：期望立即到达、离线保留、只在线到达、覆盖旧消息、撤回消息，还是需要短信补充兜底。

建议在测试环境中优先使用 Registration ID 定向推送，避免标签、别名、分群等目标条件影响基础链路判断。

先判断问题发生在哪一层

现象	优先检查	常见原因
API 直接返回失败	Push API 返回码、鉴权、请求体格式	AppKey/Secret 错误、JSON 格式错误、目标为空、字段取值非法、配额不足
控制台显示推送失败	推送记录中的失败原因	目标条件不匹配、厂商配额不足、平台参数错误
推送成功但单设备没收到	消息查询、设备查询、Registration ID	Registration ID 失效、设备不属于该 AppKey、设备离线、通知权限关闭
Android 没走厂商通道	厂商 token、下发策略、配额查询	厂商 SDK 未集成成功、未获取 token、策略不匹配、配额已用完
iOS 收不到通知	APNs 环境、证书或 Token Authentication、`apns_production`	生产/开发环境不一致、证书过期、Bundle ID 不匹配、设备 token 变化
送达率低但请求成功	推送记录、统计 API、回执、厂商分类	用户离线、通知权限关闭、厂商限额/QPS、消息分类不合规、离线时长过短
点击率异常	点击跳转配置、客户端回调、落地页状态	跳转地址错误、客户端未处理点击回调、消息已过期但落地页未校验

控制台排查

推送记录

进入【极光控制台】-【消息推送】-【推送管理】-【推送记录】查看任务状态。

建议重点查看：

推送状态：推送成功表示极光服务已处理完成推送任务请求，不等于所有设备都已收到。
消息体：点击消息体查看完整 JSON，确认实际下发内容是否符合预期。
平台和通道数据：Android 可查看极光通道、厂商通道等维度的数据。
折损原因分析：查看不同阶段的失败或折损比例。
消息排查入口：从推送记录进入消息生命周期排查时，需要同时指定 Message ID 和设备 Registration ID。

华为和魅族通道需要配置厂商送达回执后，送达数据才会更精准；仅小米和极光通道支持展示率统计。

排查工具

进入【极光控制台】-【极光推送】-【管理工具】-【排查工具】。

常用工具：

消息查询：输入 Message ID 和 Registration ID，查看消息生命周期、失败环节、失败码、消息基本信息和设备基本信息。
设备查询：输入 Registration ID，查看设备在线状态、注册时间、通知权限、是否支持厂商下发、厂商 token 信息。
配额查询：查看小米、OPPO、vivo 等厂商通道当日配额和余量；配额不足时，消息可能切换到极光通道，强制厂商通道时可能失败。

服务端 API 排查

请求提交阶段

服务端首先确认 Push API 是否返回成功。

成功返回时，应保存 msg_id，用于后续查询推送记录、统计和消息生命周期。
失败返回时，优先根据返回码修正鉴权、请求体、目标、平台、厂商字段或配额问题。
使用别名、标签、分群推送时，需要确认目标值与客户端上报值一致。
使用 Registration ID 推送时，需要确认 Registration ID 属于当前 AppKey，且没有因卸载重装、清数据、换包等行为变化。

统计与状态查询

建议使用统计 API 建立推送结果观察口径：

GET /v3/received/detail：按 msg_id 查看送达统计详情，可区分极光通道、Android 厂商通道、iOS APNs、HarmonyOS 等维度。
POST /status/message：用于查询一条消息在一组设备上的送达状态，适合 VIP 场景下的单消息排查。
回执 API：用于接收送达、未送达、点击、推送成功等明细数据，适合自建监控和业务分析。

统计数据可能会随客户端送达持续增加，不建议把刚发送后的瞬时统计直接作为最终结果。

Android 排查

Android 推送通常需要同时区分极光通道和厂商通道。

客户端集成

确认 JPush SDK 初始化成功，并能获取当前 Registration ID。
确认目标机型对应的厂商 SDK 已正确集成。
确认厂商 token 回调正常，例如小米、华为、荣耀、OPPO、vivo、魅族、FCM、华硕、鸿蒙等。
检查应用通知权限是否开启，Android 8.0 及以上还需要关注通知渠道配置。
如果使用点击跳转、自定义铃声、角标、通知样式等能力，确认客户端配置与服务端字段一致。

厂商通道

如果设备没走厂商通道，建议按以下顺序排查：

设备查询中确认是否有对应厂商 token。
检查厂商后台配置、包名、签名、AppID、AppKey、AppSecret 等是否正确。
检查 options.third_party_channel 下的 distribution、distribution_fcm、distribution_customize 是否符合期望。
检查厂商配额和 QPS，尤其是小米、OPPO、vivo 等存在配额查询能力的厂商。
检查消息分类字段，例如 options.classification、channel_id、importance、category、notify_level、模板字段等。
确认消息内容是否符合厂商分类规则，避免营销内容使用系统消息分类。

iOS 排查

iOS 通知链路重点关注 APNs 环境、证书和设备 token。

确认证书或 Token Authentication 配置有效，Bundle ID 与应用一致。
确认开发环境和生产环境一致；API 下发时通过 options.apns_production 指定 APNs 环境。
确认用户已授权通知权限，且设备 token 已成功注册并同步至极光。
如果使用通知展示统计，确认已接入 iOS Service Extension 和展示统计接口。
如果使用消息覆盖，检查 options.apns_collapse_id 是否按业务事件稳定生成。
如果用户点击后未进入预期页面，检查客户端通知点击回调和跳转参数。

HarmonyOS 排查

HarmonyOS 通道建议重点检查以下内容：

SDK 初始化、AppKey、包名和权限配置是否正确。
是否能获取 HarmonyOS 平台对应的 Registration ID。
如果使用厂商通知能力，检查 notification.hmos 下的 category、test_message、receipt_id 等字段。
如果配置下发策略，检查 options.third_party_channel.hmos.distribution 是否符合预期。
使用统计 API 查看 hmos_hmpns_sent、hmos_hmpns_received、hmos_msg_sent、hmos_msg_received 等指标。

常见场景处理

单台设备收不到

用 Registration ID 定向发送一条测试消息。
在消息查询中输入 Message ID 和 Registration ID 查看生命周期。
在设备查询中确认设备是否属于当前 AppKey、是否在线、通知权限是否开启、厂商 token 是否存在。
如果是 Android 离线设备，优先确认厂商通道是否可用；如果只走极光通道，设备离线时无法收到。
如果是 iOS，确认 APNs 环境、证书和用户通知权限。

部分用户收不到

对比收到和未收到用户的机型、系统版本、App 版本、SDK 版本、通知权限和厂商 token。
检查是否只影响某个厂商、某个平台或某个 App 版本。
检查标签、别名、分群条件是否只命中部分人群。
检查厂商配额、QPS、运营消息单设备数量限制。
查看推送记录的折损原因分析和统计 API 的通道维度数据。

运营消息送达率波动

确认消息分类是否为运营消息或营销类消息。
检查单用户频控和厂商运营消息策略。
避免在同一时间集中发送大量运营消息，可使用定时、分批和分群策略。
不要将营销、推荐、活动消息伪装为系统消息，以免影响厂商通道稳定性。

重要消息未达

确认是否已申请并配置厂商重要消息分类。
检查 options.classification=1 及各厂商分类字段是否正确。
设置合理的 time_to_live，避免设备短暂离线就丢失消息。
对强到达场景配置短信补充，推送未及时送达时使用短信兜底。
接入送达、未送达和点击回执，形成可追踪闭环。

自定义消息收不到

自定义消息通常依赖设备在线；如果设备离线，可能无法及时收到。
仅部分厂商支持自定义消息通过厂商通道下发，且需要满足对应厂商能力限制。
对离线仍需提醒用户的场景，可使用自定义消息转厂商通知能力。
检查客户端自定义消息回调是否实现，前后台处理逻辑是否一致。

排查记录模板

建议每次排查都记录以下信息，方便复盘和升级极光支持：

信息	示例
AppKey	当前应用 AppKey
Message ID	API 返回或控制台推送记录中的 `msg_id`
Registration ID	目标设备当前有效 Registration ID
平台/机型	Android / iOS / HarmonyOS，具体品牌和系统版本
SDK 版本	客户端集成的 JPush SDK 版本
推送方式	API / 控制台 / 定时 / A/B 测试
推送类型	通知消息 / 自定义消息 / 通知 + 自定义消息
下发策略	极光通道、厂商优先、极光优先厂商辅助等
生命周期结果	成功、失败环节、错误码、错误提示
设备状态	在线状态、通知权限、厂商 token、最近注册时间

上线前检查清单

API 请求成功后已保存 msg_id。
客户端能获取并上报最新 Registration ID。
Android 厂商 token 获取正常，厂商后台配置正确。
iOS APNs 环境、证书或 Token Authentication 配置正确。
HarmonyOS 包名、权限、厂商参数配置正确。
标签、别名、Registration ID 等目标条件与业务系统一致。
重要通知已配置消息分类、离线保留和必要的短信补充。
运营消息已配置频控、分群和厂商运营消息策略。
已接入推送记录、排查工具、统计 API 或回执 API。
已准备排查记录模板，便于快速定位线上问题。