一、能收到离线推送但收不到在线推送，如何处理？
现象：能收到离线推送，但收不到在线推送。
处理：请确认：
·前台开关是否打开（对应 disablePostNotificationInForeground 接口调用）。
·发送端消息是否携带有效的 OfflinePushInfo，title 和 desc 至少一个不为空，disablePush 为 false。
·接收端在前台。
二、在线时收不到 onRecvPushMessage 回调，如何处理？
现象：在线场景下收不到 TIMPushListener.onRecvPushMessage 推送回调。
原因：下发时未设置推送信息，或 TIMPush 与 IM SDK 版本不一致。
处理：
1. 请确认 服务端 和 客户端 下发消息时，是否设置 OfflinePushInfo，未设置，或 title、desc、ext 全部为空，则收不到 onRecvPushMessage 推送监听回调。
2. TIMPush 推送插件是基于 IM SDK 进行封装，两者之间版本需要保持一致。
三、强制停止应用后收不到推送，如何处理？
现象：前台或后台能收到推送，强制停止应用后收不到。
原因：应用被强制停止后 IM 长连接已断开，只能依赖厂商离线通道送达。“前台或后台能收、强制停止后收不到”，说明问题在厂商离线通道，而不是 IM 在线链路。
处理：请按以下顺序排查：
1. 确认测试方式是真正的强制停止（从多任务划掉应用可能进程仍在），并使用 离线接入测试工具 复测。
2. 核对该设备品牌的厂商证书已在控制台配置，且客户端已集成对应厂商通道、registerPush 成功。
3. 自定义消息需在发送时设置 offlinePushInfo 的 desc 字段，否则默认不推送。
4. 部分厂商系统对强制停止的应用有限制（需开启自启动、后台运行等权限），属于厂商系统策略。
四、点击通知后无法跳转，如何排查？
现象：点击推送通知后，未能跳转到预期界面。
原因：可能是点击跳转配置不正确、厂商系统权限拦截，或推送链路异常。
处理：
1. 点击跳转配置检查
详细请参见 自定义点击跳转，检查：
·控制台配置点击后续动作按如下配置，选择打开应用内指定界面，插件用户会默认填写跳转参数，参数是否被修改。
·注册和回调处理点击事件，注册时机建议放在应用 Application 的 onCreate() 函数中，需要放在应用生命周期的靠前位置。
·点击回调处是否正确处理跳转逻辑。
2. 设备系统权限限制
应用进程不存在，点击通知栏跳转到应用界面，需要将应用从后台拉取到前台，部分厂商系统会去检查 App 是否开启了后台自启动或悬浮窗权限，不开启系统侧会拦截处理导致失败。
不同厂商、同一厂商不同 Android 版本，其对于应用开放的权限以及权限名称会存在不一致。经测试，小米 6 只需要开启后台弹出界面权限，而红米需要同时打开后台弹出界面和显示悬浮窗权限，需要针对不同厂商不同处理。
3. 推送链路排查
参见 收不到在线、离线推送排查流程，使用排查工具查看推送全链路详情。
五、设备通知栏设置对推送有什么影响？
离线推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
·手机设置 > 通知 > 锁屏通知 > 隐藏或者不显示通知，会影响锁屏状态下离线推送通知显示。
·手机设置 > 通知 > 更多通知设置 > 状态栏显示通知图标，会影响状态栏下离线推送通知的图标显示。
·手机设置 > 通知 > 应用的通知管理 > 允许通知，打开关闭会直接影响离线推送通知显示。
·手机设置 > 通知 > 应用的通知管理 > 通知铃声 和 手机设置 > 通知 > 应用的通知管理 > 静默通知，会影响离线推送通知铃音的效果。
·勿扰模式（Do Not Disturb）：这是 Android 系统功能，各品牌入口不同。开启后系统会抑制通知，只放行用户在勿扰设置中允许的通知，参见 Android 产品文档 NotificationManager。
六、registerPush 报错 800005、800006 或 800008，如何处理？
现象：调用 registerPush 报错 800005、800006 或 800008。
原因：不同错误码对应不同失败阶段：800005 为本机通道注册失败，800006 为本机通道失败后 FCM 兜底也失败，800008 为注册超时。
处理：
·800005 本机通道注册推送失败：核对设备品牌对应的厂商 SDK 是否集成、timpush-configs.json 是否为当前应用的最新配置、AndroidManifest 与混淆规则是否完整。日志明确指向 FCM/GMS（如 FCM unavailable）时，参见 Google FCM 收不到推送，如何处理。
·800006 本机通道注册失败后，尝试 FCM 通道也失败：先排查本机厂商通道（厂商 SDK、App ID、App Key、配置文件、包名与签名指纹），再排查 FCM 兜底（GMS 可用性、google-services.json、Firebase 初始化）。
·800008 注册推送服务超时：确认设备品牌与系统版本在厂商推送支持范围内，检查厂商推送服务在设备上的可用性（服务未安装、被禁用或网络不通），稍后重试或更换真机对照。
七、第三方推送 SDK 与 TIMPush 冲突，如何处理？
现象：接入 TIMPush 后，与应用自身或第三方推送 SDK 发生冲突。
原因：应用自身或依赖的第三方推送客户端与 TIMPush 中的第三方客户端冲突。
处理：需仅保留一个使用，具体方法参见 TIMPush 集成冲突解决。
八、为什么 Debug 版本正常，Release 版本异常？
现象：Debug 版本的 App 功能正常，Release 版本的 App 功能出现异常。
原因：该问题通常由混淆配置导致。
处理：可以添加如下混淆规则：
-keep class com.tencent.qcloud.** { *; }-keep class com.tencent.timpush.** { *; }
九、编译时报 com.huawei.agconnect 错误，如何处理？
现象：编译报错 Failed to apply plugin com.huawei.agconnect。
完整报错如下：
Caused by: org.gradle.api.internal.plugins.PluginApplicationException: Failed to apply plugin 'com.huawei.agconnect'.at org.gradle.api.internal.plugins.DefaultPluginManager.doApply(DefaultPluginManager.java:173)at org.gradle.api.internal.plugins.DefaultPluginManager.apply(DefaultPluginManager.java:146)
原因：agconnect 插件版本过低。
处理：将 classpath 'com.huawei.agconnect:agcp:1.6.0.300' 替换升级为 classpath 'com.huawei.agconnect:agcp:1.9.1.301'。
十、华为或荣耀注册报错（907135702 等），如何处理？
现象：华为或荣耀注册失败，日志出现 Huawei appId missing、certificate fingerprint empty 或 907135702。
原因：华为或荣耀通道依赖厂商配置文件、Gradle 插件、包名与签名指纹共同生效，任一缺失都会导致注册失败。
处理：请逐项核对：
1. App 模块已应用对应厂商 Gradle 插件（华为 com.huawei.agconnect / 荣耀 MCS 插件）。
2. agconnect-services.json / mcs-services.json 放在 App 模块根目录（不是 src/main/assets），且来自同一个厂商应用。
3. applicationId 与厂商控制台填写的包名完全一致。
4. 当前测试包的 SHA-256 签名指纹与厂商控制台填写的一致（Debug 与 Release 包签名不同，需分别核对）。
5. 修改厂商控制台配置后，需重新下载 JSON 配置文件、重新构建并重新安装。
验证信号：构建日志显示厂商配置文件被读取（如 Using the AGConnect-Config file: …）；registerPush success 且 RegistrationID 非空。
十一、华为设备注册失败且 Token 为空，如何处理？
现象：华为部分设备注册失败，Token 为空，日志通常包含："HMS token within 24h, not allowed apply hms token."。
原因：项目中的第三方依赖可能影响 Token 获取。目前已知 com.github.ihsanbal:LoggingInterceptor 可能导致该问题。
处理：先使用相同推送配置创建空项目测试。若空项目可以正常获取 Token，请逐一恢复原项目依赖，定位并升级或移除冲突依赖；若空项目仍然失败，请使用 排查工具 检查推送注册链路。
十二、华为推送报错 80300002（Android），如何处理？
现象：通过华为通道向 Android 设备下发推送时，返回错误码 80300002，含义为"对指定 Token 下发消息无权限"。若错误信息中包含 harmony requestid，则为 HarmonyOS 推送，请参见 HarmonyOS 平台问题中的 80300002 条目。
原因：华为服务端判定当前应用无权向该 Token 下发消息。常见原因包括：AppGallery Connect 未开通推送服务；控制台中填写的应用凭证与设备 Token 所属的应用不一致；应用在国内推送正常、在海外环境报错时，未开通海外 Push 权益。
处理：请依次排查：
1. 登录 AppGallery Connect，在项目设置 > API 管理中确认已开启推送服务的权限。
2. 核对腾讯云控制台华为证书中的 AppID、AppSecret，是否与客户端使用的 agconnect-services.json 属于同一个华为应用。注意 AppGallery Connect 中项目和应用各有一组 Client ID、Client Secret，需使用应用的那一组。
3. 若应用在国内推送正常，仅在海外环境报错，需要开通海外 Push 权益：登录 AppGallery Connect，选择“开发与服务”，在项目下的应用列表中选择需要开通的应用，前往“项目设置 > API 管理”，关闭 Push 服务后重新启用。如果只开通推送服务，请先在应用市场上传一个 APK 并保存为草稿，否则重新添加应用时可能找不到原来的应用。其他处理方法见 错误码 中华为的 80300002。
4. 在华为推送运营平台，用同一个 Token 手动推送一条测试消息，以区分是配置、权益问题还是 Token 问题。
十三、OPPO 手机收不到推送，如何排查？
现象：OPPO 手机收不到推送。
原因：OPPO 手机收不到推送一般有以下几种情况：消息分类配置与 OPPO 当前规则不符，或系统通知栏默认关闭。
处理：
·新接入的应用使用 category 和与之匹配的模板。IM 聊天消息申请通讯与服务类，category 填 IM。仅已开通私信通道的存量应用，继续使用已登记的私信 ChannelID，配置方法可以参见 setAndroidOPPOChannelID。详细配置参见 OPPO 厂商配置。
·notify_level（选填）：通讯与服务类消息不传时 OPPO 默认按 2（通知栏和锁屏提醒）处理；内容与营销类消息只能为 1。如需横幅等强提醒（notify_level = 16），需先单独向 OPPO 申请（仅 OPPO 应用商店二级分类属于聊天交友、电话短信、办公类的应用可申请）；未获批前不要配置 16，保持默认的 2 即可正常走通讯与服务类推送。详见 OPPO 厂商配置。
·OPPO 安装应用通知栏显示默认关闭，需要确认下开关状态。
十四、小米或 vivo 手机收不到推送，如何处理？
现象：小米、vivo 设备收不到厂商通道推送。一般会提示：应用在黑名单中，禁止发送消息；或该 App 已关闭 push 通道。
原因：应用未上架对应应用市场，无法通过厂商通道下发。
处理：需要上架应用市场后，才可以通过厂商通道进行下发。
十五、小米推送报错 10016、10041 或 200001，如何处理？
现象：小米通道下发失败，小米返回的错误码为 10016、10041 或 200001。
原因与处理：
·10016：小米定义为缺失必选参数，具体缺少哪个参数以返回的 reason 为准。私信消息需要同时携带 channel_id、模板 id 和模板参数，如果 reason 指向模板相关参数为空，请核对控制台证书或发送参数中是否已配置小米 ChannelID、模板 ID 和模板参数。
·10041：小米模板接入指南中的错误示例，reason 为 Template parameter value must be String type。请检查模板参数 JSON 中每个变量的值是否都是字符串，且参数个数与模板预配置的一致。
·200001：超过小米当日推送数量限制（reason 为 exceed quota）。私信消息不限量，公信消息单日总量按应用通知开启用户数乘以倍数计算。响应中的 day_quota 和 day_acked 分别表示当日可下发总量和已送达数。建议将 IM 聊天等消息接入私信消息；确需提高额度的，可按小米说明发邮件申诉。
小米说明参见 服务端错误码参考、小米推送模板接入指南 和 小米推送消息限制说明。小米私信模板的配置参见 厂商消息分类使用指南。
十六、vivo 推送报错 10302，如何处理？
现象：vivo 推送报错 10302，提示用户 ID 不合法。
原因：有 4 种情况：
·目标 UserID 不存在。
·用户卸载应用、主动解除订阅或清除应用数据，导致原有推送绑定失效。
·设备超过 14 天没有和 vivo 推送服务器建立长连接，vivo 会判定该设备的 regId 失效，参见 vivo 推送介绍。
·测试推送时，设备未加入测试设备集。
处理：请按对应原因处理：
·目标 UserID 不存在：确认目标用户已创建，并已在真机完成登录和推送注册。
·推送绑定失效（包括设备长时间未联网导致的失效）：重新打开或安装应用，完成登录后再次调用 registerPush，确认 RegistrationID 非空。
·设备未加入测试设备集：分别在 IM 控制台选择测试推送，并在 vivo 推送运营后台添加测试设备。
| IM 控制台选择测试推送 | vivo 推送运营后台添加测试设备 |
| | |
十七、vivo 推送报错 10096 或 10097，如何处理？
现象：vivo 推送报错 10096 或 10097。
原因： 10096 表示 category 的取值无效，category 必须大写；10097 表示 category 与 classification 不是正确的对应关系，例如 classification 为 0（运营消息）时 category 填了 IM。
处理：IM 聊天消息的 category 填大写 IM，其他消息按 vivo 消息分类说明 中的取值填写。建议只设置 category（例如客户端 setAndroidVIVOCategory / vivo.category、服务端 VIVOCategory），无需同时设置旧版选填字段 classification；如果同时传了，请保证两者的对应关系正确。详见 vivo 服务端 API 接口文档。vivo 厂商配置参见 vivo 厂商配置。
十八、vivo 的本地通知 CHANNEL_ID 需要填到腾讯云吗？
不需要。根据 vivo 说明，vivo 推送固定支持系统消息和运营消息两类渠道，不支持自定义渠道，也不支持设置 channelid，详见 vivo 推送常见问题。应用在运行时调用 NotificationManager.notify() 发出的本地通知，其渠道由 vivo 的本地通知分类管理，详见 vivo 消息分类说明。
IM 离线推送使用 vivo 的消息分类参数 category：在 V2TIMOfflinePushInfo 中调用 setAndroidVIVOCategory 设置，或在腾讯云控制台证书中配置默认值，即时消息填 IM。详细说明参见 vivo 厂商配置。
十九、自集成 vivo 模板推送配置为“打开应用”时拿不到 ext，如何处理？
现象：客户端自集成 vivo 推送 SDK（未使用 TIMPush 插件）并使用 vivo 模板推送下发消息时，控制台点击后续动作配置为打开应用（打开首页），点击通知后可以拉起应用首页，但客户端从 Intent 中获取不到自定义透传参数 ext（ext 为 null）。
原因：根据 vivo 模板推送服务端 API 文档，vivo 新版模板推送接口已废弃原有的客户端自定义键值对字段 clientCustomMap，要求将自定义参数拼接到 clickAction.uri 中传递，且 clickAction.uri 仅在 clickAction.type 为 1（跳转指定应用内页）或 2（跳转网页）时生效。当点击动作配置为打开应用（对应 clickAction.type = 0）时，vivo 系统直接拉起应用首页，即使传入 uri 也会在系统侧丢弃该字段，因此无法携带 ext。
处理：如果自集成 vivo 推送且需要在模板推送下获取 ext，请按以下方式之一处理：
1. 改用“打开应用内指定界面”：在腾讯云控制台将点击后续动作配置为打开应用内指定界面（对应 clickAction.type = 1），填写客户端目标 Activity 的自定义 URI，并在目标 Activity 中通过 getIntent().getExtras().getString("ext") 获取透传参数。vivo 适配说明参见 vpush 消息模板接入指南 和 vivo push 接入类问题。
2. 接入 TIMPush 插件：使用 TIMPush 插件时，即使控制台配置为打开应用，服务端也会通过插件内置页面（type = 1）中转携带 ext 并拉起应用首页，客户端可通过 TIMPushListener.onNotificationClicked 正常获取 ext，详见 自定义点击跳转。
20、OPPO 消息内容过长时收不到推送，如何处理？
现象：OPPO 机型发送的消息内容过长时，对方收不到推送通知。
原因：厂商推送对于 desc 推送内容有长度限制。
处理：调用 sendMessage 时，确保 V2TIMOfflinePushInfo.desc 内容不超过厂商限制长度。
21、为什么 OPPO 设备能收到 REST API 推送，却收不到客户端消息推送？
现象：通过 REST API 下发能收到推送，通过客户端发消息收不到。
原因：通过 REST API 下发消息时可以收到推送，说明客户端 OPPO 厂商推送配置正常。客户端发消息时未携带离线推送参数 OfflinePushInfo。
处理：发起消息发送请求时需携带 OfflinePushInfo。客户端 API 提供 V2TIMOfflinePushInfo 入参用于配置该信息，具体参数规范及使用方式参见 发送消息 API 文档。
22、Google FCM 收不到推送，如何处理？
现象：使用 Google FCM 通道收不到推送。
原因：IM 控制台证书未正确上传或配置不正确；设备所在网络的防火墙拦截了 FCM 连接；设备处于省电状态（Doze 或 App Standby）。
处理：
·证书配置：参见文档 厂商配置 > Google FCM 检查证书是否添加正确。
·网络防火墙：如果设备所在网络有防火墙，需放行 TCP 端口 5228、5229、5230 和 443（FCM 通常使用 5228，有时使用 5229 和 5230），参见 Configure your Network for FCM。
·省电状态：设备处于 Doze 或应用处于 App Standby 时，FCM 普通优先级消息会推迟到系统的维护窗口，或用户唤醒设备后才送达。可先唤醒设备（亮屏、接上电源）后复测，参见 Android 产品文档 针对低电耗模式和应用待机模式进行优化。
23、FCM 推送有哪些注意事项？
·如果想优先走 FCM 通道，请使用接口 forceUseFCMPushChannel。
·FCM 推送消息可能会拉起应用进程，请不要在应用启动处，即 Application 的 onCreate() 生命周期内做登录、数据上报等不适合高频并发的逻辑。
24、支持向三星、中兴、传音等手机推送吗？
·在线推送：支持所有机型，包括三星、中兴、传音、坚果、海信、索尼等。
·离线推送：支持的厂商通道为华为、荣耀、小米、OPPO、vivo、魅族、APNs（含一加、realme、iQOO 等子品牌）及 Google FCM，参见 计费说明。三星、中兴、传音等品牌没有独立的厂商离线通道：海外设备在具备 GMS 服务和网络条件时可通过 FCM 通道接收离线推送；国内设备大多未安装 GMS 服务，不支持离线推送。