即时通信 IM文档中心入门中心API 中心SDK 中心文档活动我的反馈文档反馈官招募中，报名立赚积分兑换代金券！> HOT文档中心>即时通信 IM>推送服务（Push）>常见问题常见问题最近更新时间：2025-09-22 20:41:22
微信扫一扫QQ新浪微博复制链接链接复制成功我的收藏本页目录：Android收不到离线推送怎么排查？跳转界面不成功怎么排查？海外推送指南FCM 推送问题解决接入冲突问题其他问题推送只能收到两条/或者几条，测试工具显示发送成功，之后就收不到了，是什么问题？TIMPush 接入，离线情况下接收新消息能收到推送通知，但在线情况下却收不到 TIMPushListener.onRecvPushMessage 推送回调，是为什么？TIMPush 插件接入，OPPO 机型，当发送的消息内容过长时对方收不到推送通知？TIMPush 插件接入，OPPO 机型，推送注册成功后，通过 RestAPI 下发推送能收到，但是通过客户端发送消息，却收不到消息推送？TIMPush 接入，编译运行时报关于 “com.huawei.agconnect” 错误，完整报错如下：客户端接入推送插件，收不到在线推送，可以收到离线推送，是什么问题？iOS普通消息为什么收不到离线推送？自定义消息为什么收不到离线推送？如何关闭离线推送消息的接收？收不到推送，且后台报错 bad devicetoken。iOS 注册报错："errCode"：3000，"errMsg"："未找到应用程序的“aps-environment”的授权字符串"iOS 开发环境下，注册偶现不返回 deviceToken 或提示 APNs 请求 token 失败？iOS 没有收到触达回执iOS 证书过期iOS 统计上报功能APNs、VoIP 和 LiveActivity 区别iOS 接入失败，控制台测试工具返回 Token 与证书不匹配？管理员发送的账号收不到 onRecvPushMessage，(BOOL)onRemoteNotificationReceived:(nullable NSString *)notice 这个方法执行了，但是 notice 是空字符串，该如何处理？报错：dyld: Library not loaded: @rpath/ImSDK_Plus.framework/ImSDK_Plus，Referenced from: /private/var/containers/Bundle/Application/52F5B9F2-435F-4BBF-BF7D，3EC3B381CE80/Demo.app/Frameworks/TIMPush.framework/TIMPush，Reason: image not found？APNs 推送，厂商返回错误码信息 code: 403 , reason: InvalidProviderToken？触达统计是否有延迟？FlutterFlutter 端，tencent_cloud_chat_push 推送插件升级使用 8.1 版本，调用 registerPush 接口注册推送被踢，影响使用，该如何处理？配置 FCM 推送信息后，使用 OPPO 机型测试，由于插件内部默认走 OPPO 通道，导致注册推送时，报“oppo推送注册失败”，该如何解决？注册 FCM 推送时报“Default FirebaseApp is not initialized in this process com.tencent.flutter.tuikit. Make sure to call FirebaseApp.initializeApp(Context) first.” 错误，该如何解决？Flutter tencent_cloud_chat_push 推送插件接入，点击推送通知，不触发 “onNotificationClicked” 回调，日志如下： TUICallKit + TIMPush 接入，切后台接收通话邀请，点击推送通知，应用不跳转至“通话邀请界面” ，如何解决？小程序/v4/timpush/batch 接口请求成功后，IM 控制台 > 推送数据统计 > 指定 UserID 标签页下没有记录？其他问题Android收不到离线推送怎么排查？1.特殊情况排查OPPO 手机OPPO 手机收不到推送一般有以下几种情况：按照 OPPO 推送官网要求，在 Android 8.0 及以上系统版本的 OPPO 手机上必须配置 ChannelID，否则推送消息无法展示。配置方法可以参见 setAndroidOPPOChannelID。OPPO 安装应用通知栏显示默认关闭，需要确认下开关状态。Google FCM收不到推送需要确认下 IM 控制台是否正确上传证书。排查路径参见文档 IM 控制台配置 > Google FCM，对照示意图看下是否添加正确。小米和 vivo小米和 vivo：需要上架应用市场后，才可以通过厂商通道进行下发。一般会提示：应用在黑名单中，禁止发送消息。或者，该 App 已关闭 push 通道。发送消息为自定义消息自定义消息的离线推送和普通消息不太一样，自定义消息的内容我们无法解析，不能确定推送的内容，所以默认不推送，如果您有推送需求，需要您在 sendMessage 的时候设置 offlinePushInfo 的 desc 字段，推送的时候会默认展示 desc 信息。设备通知栏设置影响离线推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：手机设置 > 通知 > 锁屏通知 > 隐藏或者不显示通知，会影响锁屏状态下离线推送通知显示。手机设置 > 通知 > 更多通知设置 > 状态栏显示通知图标，会影响状态栏下离线推送通知的图标显示。手机设置 > 通知 > 应用的通知管理 > 允许通知，打开关闭会直接影响离线推送通知显示。手机设置 > 通知 > 应用的通知管理 > 通知铃声和手机设置 > 通知 > 应用的通知管理 > 静默通知，会影响离线推送通知铃音的效果。消息分类厂商推送都有消息分类机制，不同类型也会有不同的推送策略，详情请参见 推送消息分类。厂商特性离线推送依赖厂商能力，一些简单的字符可能会被厂商过滤不能透传推送，建议使用有意义的内容进行推送。2.自助推送排查工具设备推送插件接入是否正常在 IM 控制台通过 离线测试工具 自测下是否可以正常推送。推送链路排查使用 排查工具 查看推送全链路推送详情。跳转界面不成功怎么排查？1.点击跳转配置检查详细参见 自定义点击跳转，检查：控制台配置点击后续动作按如下配置，选择打开应用内指定界面，插件用户会默认填写跳转参数，参数是否被修改。注册和回调处理点击事件，注册时机建议放在应用 Application 的 onCreate() 函数中，需要放在应用生命周期的靠前位置。点击回调处是否正确处理跳转逻辑。2.设备系统权限限制应用进程不存在，单击通知栏跳转到应用界面，需要将应用从后台拉取到前台，部分厂商系统会去检查 App 是否开启了后台自启动或悬浮窗权限，不开启系统侧会拦截处理导致失败。不同厂商、同一厂商不同 Android 版本，其对于应用开放的权限以及权限名称会存在不一致。经测试，小米6只需要开启后台弹出界面权限，而红米需要同时打开后台弹出界面和显示悬浮窗权限，需要针对不同厂商不同处理。3.推送链路排查使用 排查工具 查看推送全链路推送详情。海外推送指南1. 海外离线推送支持的厂商有 FCM、华为、OPPO 和 APNs。2. FCM 通道必备充分条件是：设备可以访问海外网站、设备有安装支持 GMS 服务、成功集成 TIMPush。注意：国内设备大部分没有安装 GMS 服务，无法支持 FCM 推送。FCM 推送问题1. 如果想让优先走 FCM 通道，请使用接口 forceUseFCMPushChannel 。2. FCM 推送消息可能会拉起应用进程，请不要在应用启动处，即 application 的 onCreate() 生命周期内做登录、数据上报等不适合高频并发的逻辑。解决接入冲突问题接入产生冲突的原因是应用程序自身集成或者依赖的第三方推送客户端，与 TIMPush 中的第三方客户端产生冲突，需要仅保留一个使用。具体方法请参见：TIMPush 集成冲突解决。其他问题支持向三星、中兴、传音、坚果、海信、索尼等手机推送吗？在线推送支持所有机型，包括三星、中兴、传音、坚果、海信、索尼等。华为华为推送证书 ID <= 11344 ，使用华为推送 v2 版本接口，不支持触达和单击回执，如需要统计数据功能，请重新生成更新证书 ID 。AndroidInfo.ExtAsHuaweiIntentParam，传“1”表示将透传内容 Ext 作为 Intent 的参数，“0”表示将透传内容 Ext 作为 Action 参数。restapi 使用“1”暂时不支持点击事件统计。数据统计功能只会记录最后一个登录设备的推送数据详情，不支持多端登录场景。Debug 版本的 App 功能正常，Release 版本的 App 功能出现异常 出现此问题很大概率是混淆导致的，可以添加如下混淆规则：-keep class com.tencent.qcloud.** { *; }-keep class com.tencent.timpush.** { *; }推送只能收到两条/或者几条，测试工具显示发送成功，之后就收不到了，是什么问题？大概率是消息分类被厂商默认归类为营销类，限制每天的下发条数。可以按照 消息分类汇总文档 申请和适配。注意：注意：消息分类每个厂商不一样，有些需要先申请开通，某些厂商申请之后生效有一定的时间。消息分类字段：通常控制台证书页面可以填写默认值，例如 category。RestAPI 和客户端接口也都提供了对应的字段或方法，来覆盖控制台默认值，达到有多种分类的效果.TIMPush 接入，离线情况下接收新消息能收到推送通知，但在线情况下却收不到 TIMPushListener.onRecvPushMessage 推送回调，是为什么？IM SDK 需要和 TIMPush 插件版本保持一致。TIMPush 插件接入，OPPO 机型，当发送的消息内容过长时对方收不到推送通知？厂商推送对于 desc 推送内容有长度限制，可在 sendMessage 时设置 V2TIMOfflinePushInfo.desc 内容不超过限制长度。TIMPush 插件接入，OPPO 机型，推送注册成功后，通过 RestAPI 下发推送能收到，但是通过客户端发送消息，却收不到消息推送？此种问题一般都是因为客户在 IM 控制台配置的推送点击事件为“跳转到指定页面”，但填写的自定义路径不正确引起，建议使用 IM 组件的默认路径。TIMPush 接入，编译运行时报关于 “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)解决方法：classpath 'com.huawei.agconnect:agcp:1.6.0.300' 替换升级为：classpath 'com.huawei.agconnect:agcp:1.9.1.301'。客户端接入推送插件，收不到在线推送，可以收到离线推送，是什么问题？有几个点可以确认下：前台开关是否打开（对应 disablePostNotificationInForeground 接口调用）。发送端消息是否带有效的 offlinePushInfo，title 不要为空，disablePush 为 false。接收端在前台。iOS普通消息为什么收不到离线推送？首先，请检查下 App 的运行环境和证书的环境是否一致，如果不一致，收不到离线推送。其次，检查下 App 和证书的环境是否为生产环境。如果是开发环境，向苹果申请 deviceToken 可能会失败，生产环境暂时没有发现这个问题，请切换到生产环境测试。自定义消息为什么收不到离线推送？自定义消息的离线推送和普通消息不太一样，自定义消息的内容我们无法解析，不能确定推送的内容，所以默认不推送，如果您有推送需求，需要您在 sendMessage 的时候设置 offlinePushInfo 的 desc字段，推送的时候会默认展示 desc 信息。如何关闭离线推送消息的接收？如果您想关闭离线推送消息的接收，调用 unRegisterPush 即可。收不到推送，且后台报错 bad devicetoken。Apple 的 deviceToken 与当前编译环境有关，请检查：1. 接入流程中 配置推送参数 的 businessID 是否是对应环境的证书 ID。2. 控制台创建证书检查：生产环境证书：上传的证书类型为 Apple Push Notification service SSL (Sandbox & Production)，并在Archive 出Release 包后进行测试。注意：不可在 Xcode 测试。开发环境证书：您需要 Archive 出 release 包后进行测试，创建选择正确证书即可。iOS 注册报错："errCode"：3000，"errMsg"："未找到应用程序的“aps-environment”的授权字符串"原因1：在 Xcode 项目中未启用推送通知权限，检查 Xcode 配置。开启方法参考：Xcode添加推送权限。原因2：在应用归属的 AppleID 账号下，对应应用未勾选 Push Notifications 开启远程推送服务。可以查看描述文件是否包含 “aps-environment”， 以及是否对应正确开发/生产环境。开启方法参考：申请 APNs 证书。iOS 开发环境下，注册偶现不返回 deviceToken 或提示 APNs 请求 token 失败？此问题现象是由于 APNs 服务不稳定导致的，可尝试通过以下方式解决：1. 给手机插入 SIM 卡后使用4G网络测试。2. 卸载重装、重启 App、关机重启后测试。3. 打生产环境的包测试。4. 更换其它 iOS 系统的手机测试。iOS 没有收到触达回执1. 上报推送触达数据，需要开启控制台开关来支持 iOS 10 的 Extension 功能，详情请参见 统计推送抵达率。2. 为保证上报数据在一些异常情况下不丢失，iOS 推送数据的上报会在下次登录时候才上报，可能会有滞后，请尝试重新登录。iOS 证书过期在 IM 控制台单击编辑对应证书，更新下 p12 证书即可。需要注意的是：请勿删除证书重新创建，重新创建证书 ID 会变化，需要发版本支持更新。iOS 统计上报功能上报推送触达数据，需要开启此开关来支持 iOS 10 的 Extension 功能，详情请参见 统计推送抵达率。APNs、VoIP 和 LiveActivity 区别特性APNsVoIPLiveActivity使用场景发送通知提醒用户音视频通话显示实时更新的动态内容生命周期跟随通知栏跟随通知栏持续到事件结束SDK 集成集成 TIMPush集成 CallKit 和 TUICallKitVoIPExtension集成 ActivityKit 和 IMSDK使用方式申请 APNs 推送证书，端上上报 token，后台校验和触发申请 VoIP 推送证书，端上上报 token，后台校验和触发应用可主动更新申请推送 P8 证书，端上上报 token，后台校验和触发推送 token设备级别设备级别与特定实时活动相对应，一台手机可同时创建多个实时活动限制通知内容有限需要 VoIP 证书和 iOS CallKitiOS 16 以上支持实际效果iOS 接入失败，控制台测试工具返回 Token 与证书不匹配？iOS 推送证书分正式环境和测试环境，Token 也分正式环境。Token 和证书必须对应上才能推送。1. Token 是正式还是测试取决于客户端打包方式，先确认环境是否正常：开发环境（Xcode 直接运行），由 Debug 设置配置 上传的证书 ID。生产环境（打包 ipa），release 设置配置上传的证书 ID。（大部分客户常把生产的证书上传到开发环境）。2. p12 证书可以选择开发/生产一体的证书，或者使用 p8 证书。上传到 IM 控制台选择想要的环境就行。管理员发送的账号收不到 onRecvPushMessage，(BOOL)onRemoteNotificationReceived:(nullable NSString *)notice 这个方法执行了，但是 notice 是空字符串，该如何处理？确认客户服务端接口调用有没有设置 OfflinePushInfo，建议设置后试试，onRemoteNotificationReceived 对应的 Ext 字段。报错：dyld: Library not loaded: @rpath/ImSDK_Plus.framework/ImSDK_Plus，Referenced from: /private/var/containers/Bundle/Application/52F5B9F2-435F-4BBF-BF7D，3EC3B381CE80/Demo.app/Frameworks/TIMPush.framework/TIMPush，Reason: image not found？因缺少 IM SDK 引起，先执行 pod 'TXIMSDK_Plus_iOS’ 或者 pod 'TXIMSDK_Plus_iOS_XCFramework'，加上后在执行 pod install。APNs 推送，厂商返回错误码信息 code: 403 , reason: InvalidProviderToken？客户使用的P8证书，上报的 Token 和证书不匹配导致厂商验证失败。需要注意以下几点：1. 客户端生成 regId 的时候，使用的 bundleId 要和服务端推送使用的 bundleId 一致。2. teamId 和 keyId 填写准确。3. 证书要使用正确（检查证书是否是生产环境\\测试环境）。触达统计是否有延迟？Android 的触达是厂商返回的，iOS 的触达是客户端上报的。因此 Android 什么时候触达，取决于厂商，不受 IM 控制。iOS的触达上报有延迟，是下一次客户端登录才会上报上来。FlutterFlutter 端，tencent_cloud_chat_push 推送插件升级使用 8.1 版本，调用 registerPush 接口注册推送被踢，影响使用，该如何处理？问题如下图：原因：对于使用 IM 能力+厂商推送的客户，调用 registerPush 注册推送时，AppID 和 AppKey 不需要传入（否则会启用插件内免登录逻辑）。此问题，xlog 日志中表现为 注册推送时，会伴随着 login 调用，且 UserID 和 已经登录的 UserID 不同。xlog 日志中对应登录账号的类型 account_type：Push。正确调用：配置 FCM 推送信息后，使用 OPPO 机型测试，由于插件内部默认走 OPPO 通道，导致注册推送时，报“oppo推送注册失败”，该如何解决？注册推送之前调用 setPushBrandId 指定设置 FCM 通道可解决。注册 FCM 推送时报“Default FirebaseApp is not initialized in this process com.tencent.flutter.tuikit. Make sure to call FirebaseApp.initializeApp(Context) first.” 错误，该如何解决？原因："com.google.gms:google-services" google gms 服务插件版本不兼容引起。解决方法：修改 gms 插件版本至： 4.3.15。Flutter tencent_cloud_chat_push 推送插件接入，点击推送通知，不触发 “onNotificationClicked” 回调，日志如下： 1. 首先既然能收到推送通知，说明推送配置是没有问题的。2. 可能是以下原因：客户有混合开发，导致原生端注册推送，因存在多进程导致。IM 控制台配置的推送点击方式不是“指定页面”。IM 控制台配置的推送跳转方式，指定页面填写的路径不是“插件默认路径”。TUICallKit + TIMPush 接入，切后台接收通话邀请，点击推送通知，应用不跳转至“通话邀请界面” ，如何解决？1. 需要客户检查下：在 IM 控制台 配置的 “点击后续动作” 是什么，请选择 “打开应用内指定页面”，插件接入会有默认值，使用默认值即可。2. 在推送插件 onNotificationClicked 回调内加上“自动登录”逻辑。小程序/v4/timpush/batch 接口请求成功后，IM 控制台 > 推送数据统计 > 指定 UserID 标签页下没有记录？IM 控制台页面查询的用户，需要接收了该接口的在线推送或离线推送才会有数据展示在控制台。 其他问题上架隐私合规相关请参考 App 隐私政策中应披露第三方 SDK 相关情况。收不到推送，插件费用到期推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您业务正常使用，请提前 购买/续费。关于 Push SDK 包体积如果您要求集成包体积更低，并且希望单独使用 Push 推送服务不集成 IM SDK，您可以 点击进入交流群 直接咨询。提供推送接入方法对比接入方法集成方式对比功能对比推送服务（Push）插件快速集成：不再需要逐个厂商填写配置，控制台下载引入 json 配置文件，即可完成所有手机厂商的推送信息配置。支持按需集成一个或者多个对应厂商的推送渠道包，更加满足合规要求。不需要客户处理推送注册、token 上报、前后台状态上报等，接入后插件自动闭环。不再需要关注和添加打点和上报逻辑，开启功能后插件自行上报和汇总，支持链路排查和指标统计等。插件封装界面跳转、图标自定义等方法，直接使用即可。普通消息推送。全员标签推送。自定义界面跳转。推送自定义样式。设备推送状态查询。全链路排查工具。推送记录和指标统计分析。自行集成文档自行集成。普通消息推送。上一篇: 错误码下一篇: 产品动态Copyright © 2013-2025 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有深圳市腾讯计算机系统有限公司ICP备案/许可证号：粤B2-20090059粤公网安备44030502008569号腾讯云计算（北京）有限责任公司京ICP证150476号 | 京ICP备11018762号中国站中文International文档“捉虫”活动检视指定产品文档，发现和反馈有效问题，奖！API专项"捉虫"反馈API文档问题，代金券、周边好礼奖不停！文档建议，你提了吗快来使用腾讯云产品文档，提出有效建议，奖！在线咨询目录返回顶部