即时通信 IM 离线推送

这篇会介绍如何在 Android 工程中集成 TIMPush。

一、前提条件

请确认已 开通 Push 服务 并按需完成 Android 厂商配置（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / Google FCM）。

二、方式1：AI 集成

通过 npx 安装 @tencent-rtc/trtc-push-skill 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，你可以直接向 AI 输入“集成 Android 离线推送”等需求，AI 将根据项目类型引导你完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。详情可参考 AI Coding。

三、方式2：手动集成

你可下载 Push 接入脚本工具，自动将推送构建配置写入你的 Android 工程，替代手工逐项修改，支持预览与自动备份。详细使用方法见包内说明文档。

四、步骤1：下载并添加 timpush-configs 配置文件

按需完成厂商后台、腾讯云控制台配置后，在腾讯云控制台下载 timpush-configs.json，并将其放置在应用的 assets 目录下。下载路径为：控制台 > 推送服务 Push > 推送设置 > 厂商配置 > 下载证书：

五、步骤2：集成 TIMPush SDK

在应用模块的 build.gradle 的 dependencies 中添加 TIMPush SDK。

dependencies { implementation 'com.tencent.timpush:timpush:latest.release'}

六、步骤3：集成厂商通道 SDK

小米华为OPPOvivo荣耀魅族Google FCM

在应用模块 build.gradle 的 dependencies 中追加小米通道包：implementation 'com.tencent.timpush:xiaomi:latest.release'

七、1. 添加厂商配置文件

在华为 AppGallery Connect 下载 agconnect-services.json，添加到应用模块根目录：app/agconnect-services.json。

八、2. 配置 Gradle 插件

追加厂商 Maven 仓库

Gradle 7.1 及以上Gradle 7.0 及以下在 settings.gradle 的 pluginManagement > repositories 和 dependencyResolutionManagement > repositories 中追加：maven { url "https://developer.huawei.com/repo/" }在项目级 build.gradle 的 buildscript > repositories，以及 settings.gradle 的 dependencyResolutionManagement > repositories（Gradle 7.0）或 allprojects > repositories（Gradle 7.0 以下）中追加：maven { url "https://developer.huawei.com/repo/" }

配置项目级插件依赖

Gradle 7.1 及以上Gradle 7.0 及以下在项目级 build.gradle 的 buildscript > repositories 中包含 google() 和华为仓库。buildscript { repositories { google() mavenCentral() gradlePluginPortal() maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" } maven { url "https://developer.huawei.com/repo/" } } dependencies { // 请与项目当前 Android Gradle Plugin 版本保持一致。 classpath 'com.android.tools.build:gradle:<AGP_VERSION>' // 如果项目使用 Kotlin Android 插件，请与项目当前 Kotlin Gradle Plugin 版本保持一致。 classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:<KOTLIN_VERSION>' // 华为 AGConnect。Gradle 8 / AGP 8 项目不要继续使用 1.6.0.300。 classpath 'com.huawei.agconnect:agcp:1.9.1.301' }}1. 请将<AGP_VERSION>替换为项目当前使用的 Android Gradle Plugin 版本，例如 8.9.1。2. 请将<KOTLIN_VERSION> 替换为项目当前使用的 Kotlin Gradle Plugin 版本；如果项目未使用 Kotlin Android 插件，可删除该行。警告：对于 Gradle 8 / AGP 8 项目，请不要继续使用 com.huawei.agconnect:agcp:1.6.0.300。AGP 8.0 已移除 Transform API，旧版 AGC 插件存在兼容风险，建议使用 com.huawei.agconnect:agcp:1.9.1.301 或更高已验证版本。在项目级 build.gradle 的 buildscript > dependencies 中追加：classpath 'com.huawei.agconnect:agcp:1.6.0.300'如果旧工程已升级到 Gradle 8 / AGP 8，请不要继续使用 1.6.0.300，建议改为 com.huawei.agconnect:agcp:1.9.1.301 或更高已验证版本。

在应用模块启用插件

在应用模块的 build.gradle 中启用华为插件。

plugins { // 华为 AGConnect。 id 'com.huawei.agconnect'}// 或：apply plugin: 'com.huawei.agconnect'

九、3. 集成 TIMPush 厂商依赖

在应用模块 build.gradle 的 dependencies 中追加华为通道包：

implementation 'com.tencent.timpush:huawei:latest.release'

在应用模块 build.gradle 的 dependencies 中追加 OPPO 通道包：implementation 'com.tencent.timpush:oppo:latest.release'

十、1. 集成 TIMPush 厂商依赖

在应用模块 build.gradle 的 dependencies 中追加 vivo 通道包：

implementation 'com.tencent.timpush:vivo:latest.release'

十一、2. 配置 manifestPlaceholders 和 AndroidManifest.xml

在 manifestPlaceholders 或直接在 AndroidManifest.xml 中配置 meta-data。

方法 1：配置 manifestPlaceholders方法 2：配置 AndroidManifest.xml在 manifestPlaceholders 里添加条目：android { defaultConfig { manifestPlaceholders = [ "VIVO_APPKEY": "你应用分配的证书 APPKEY", "VIVO_APPID" : "你应用分配的证书 APPID" ] }}在 AndroidManifest.xml 中配置 meta-data：<application> <!– vivo begin –> <meta-data tools:replace="android:value" android:name="com.vivo.push.api_key" android:value="你应用分配的证书 APPKEY" /> <meta-data tools:replace="android:value" android:name="com.vivo.push.app_id" android:value="你应用分配的证书 APPID" /> <!– vivo end –></application>如果使用 tools:replace，请确认 manifest 根节点包含 tools 命名空间：<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"></manifest>

十二、1. 添加厂商配置文件

在荣耀开发者服务平台下载 mcs-services.json，添加到应用模块根目录：app/mcs-services.json。

十三、2. 配置 Gradle 插件

追加厂商 Maven 仓库

Gradle 7.1 及以上Gradle 7.0 及以下在 settings.gradle 的 pluginManagement > repositories 和 dependencyResolutionManagement > repositories 中追加：maven { url "https://developer.hihonor.com/repo" }在项目级 build.gradle 的 buildscript > repositories，以及allprojects > repositories中追加：maven { url "https://developer.hihonor.com/repo" }

配置项目级插件依赖

Gradle 7.1 及以上Gradle 7.0 及以下请在项目级 Gradle 文件中额外补充 buildscript 配置，并在 dependencies 中声明 com.android.tools.build:gradle。buildscript { repositories { google() mavenCentral() gradlePluginPortal() maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" } maven { url "https://developer.hihonor.com/repo" } } dependencies { // 请与项目当前 Android Gradle Plugin 版本保持一致。 classpath 'com.android.tools.build:gradle:<AGP_VERSION>' // 如果项目使用 Kotlin Android 插件，请与项目当前 Kotlin Gradle Plugin 版本保持一致。 classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:<KOTLIN_VERSION>' // 荣耀 Push。 classpath 'com.hihonor.mcs:asplugin:2.0.1.300' }}1. 请将<AGP_VERSION>替换为项目当前使用的 Android Gradle Plugin 版本。2. 请将<KOTLIN_VERSION> 替换为项目当前使用的 Kotlin Gradle Plugin 版本；如果项目未使用 Kotlin Android 插件，可删除该行。在项目级 build.gradle 的 buildscript > dependencies 中追加：classpath 'com.hihonor.mcs:asplugin:2.0.1.300'

在应用模块启用插件

完成项目级插件依赖配置后，还需要在应用模块的 build.gradle 中启用荣耀插件。

plugins { // 荣耀 Push。 id 'com.hihonor.mcs.asplugin'}// 或：apply plugin: 'com.hihonor.mcs.asplugin'

十四、3. 集成 TIMPush 厂商依赖

在应用模块 build.gradle 的 dependencies 中追加荣耀通道包：

implementation 'com.tencent.timpush:honor:latest.release'

注意：com.hihonor.mcs:push 是 com.tencent.timpush:honor 引入的依赖，无需单独添加。如果构建时找不到该依赖，请检查是否已按上文追加荣耀 Maven 仓库 https://developer.hihonor.com/repo。

十五、4. 配置 manifestPlaceholders 和 AndroidManifest.xml

在 manifestPlaceholders 或 AndroidManifest.xml 中配置 meta-data。

方法 1：配置 manifestPlaceholders方法 2：配置 AndroidManifest.xmlandroid { defaultConfig { manifestPlaceholders = [ "HONOR_APPID": "你应用分配的证书 APPID" ] }}<application> <!– honor begin –> <meta-data tools:replace="android:value" android:name="com.hihonor.push.app_id" android:value="你应用分配的证书 APPID" /> <!– honor end –></application>如果使用 tools:replace，请确认 manifest 根节点包含 tools 命名空间：<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"></manifest>已添加的公共仓库基础上

在应用模块 build.gradle 的 dependencies 中追加魅族通道包：implementation 'com.tencent.timpush:meizu:latest.release'

十六、1. 添加厂商配置文件

在 Firebase 控制台下载 google-services.json，添加到应用模块根目录：app/google-services.json。

十七、2. 配置 Gradle 插件

配置项目级插件依赖

Gradle 7.1 及以上Gradle 7.0 及以下在项目级 build.gradle 的 buildscript > repositories 中包含 google() 等仓库：buildscript { repositories { google() mavenCentral() gradlePluginPortal() maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" } } dependencies { // 请与项目当前 Android Gradle Plugin 版本保持一致。 classpath 'com.android.tools.build:gradle:<AGP_VERSION>' // 如果项目使用 Kotlin Android 插件，请与项目当前 Kotlin Gradle Plugin 版本保持一致。 classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:<KOTLIN_VERSION>' // Google FCM。4.4.2 要求 AGP 7.3.0 及以上，更低的 AGP 请改用 4.3.15。 classpath 'com.google.gms:google-services:4.4.2' }}1. 请将<AGP_VERSION>替换为项目当前使用的 Android Gradle Plugin 版本。2. 请将<KOTLIN_VERSION> 替换为项目当前使用的 Kotlin Gradle Plugin 版本；如果项目未使用 Kotlin Android 插件，可删除该行。说明：com.google.gms:google-services:4.4.2 要求 AGP 7.3.0 及以上；如果项目的 AGP 低于 7.3.0，请改用与当前 AGP 兼容的 Google Services Gradle Plugin 版本，例如 4.3.15。在项目级 build.gradle 的 buildscript > dependencies 中追加：classpath 'com.google.gms:google-services:4.3.15'

在应用模块启用插件

在应用模块的 build.gradle 中启用 Google Services 插件。

plugins { // Google FCM。 id 'com.google.gms.google-services'}// 或：apply plugin: 'com.google.gms.google-services'

十八、3. 集成 TIMPush 厂商依赖

在应用模块 build.gradle 的 dependencies 中追加 FCM 通道包：

implementation 'com.tencent.timpush:fcm:latest.release'

厂商消息分类机制会影响消息推送的及时性，参考文档 厂商消息分类限制和使用指南 处理。

20、调用 registerPush

registerPush 用于向腾讯云 Push 后台注册当前设备的推送 token。请在用户同意隐私政策后调用 registerPush(appKey = Push Key)，示例代码如下所示：

JavaKotlinimport android.util.Log;import com.tencent.timpush.TIMPushCallback;import com.tencent.timpush.TIMPushManager;// 在用户同意隐私政策后调用private void registerTIMPush() { int sdkAppId = 0; // TODO: Replace with your SDKAppID. String appKey = "你的客户端密钥"; // TODO: Replace with your Push Key. TIMPushManager.getInstance().registerPush(this, sdkAppId, appKey, new TIMPushCallback<Object>() { @Override public void onSuccess(Object data) { Log.d("TIMPush", ">>>>> registerPush success, data = " + data); // 获取并打印出 registrationID，方便后续根据 registrationID 发送离线推送消息 TIMPushManager.getInstance().getRegistrationID(new TIMPushCallback<Object>() { @Override public void onSuccess(Object data) { String registrationID = (String) data; Log.d("TIMPush", ">>>>> getRegistrationID success, registrationID = " + registrationID); } @Override public void onError(int errCode, String errMsg, Object data) { Log.e("TIMPush", ">>>>> getRegistrationID failed, errCode = " + errCode + ", errMsg = " + errMsg); } }); } @Override public void onError(int errCode, String errMsg, Object data) { Log.e("TIMPush", ">>>>> registerPush failed, errCode = " + errCode + ", errMsg = " + errMsg); } });}import android.util.Logimport com.tencent.timpush.TIMPushCallbackimport com.tencent.timpush.TIMPushManager// 在用户同意隐私政策后调用private fun registerTIMPush() { val sdkAppId = 0 // TODO: Replace with your SDKAppID. val appKey = "你的客户端密钥" // TODO: Replace with your Push Key. TIMPushManager.getInstance().registerPush(this, sdkAppId, appKey, object : TIMPushCallback<Any?>() { override fun onSuccess(data: Any?) { Log.d("TIMPush", ">>>>> registerPush success, data = $data") // 获取并打印出 registrationID，方便后续根据 registrationID 发送离线推送消息 TIMPushManager.getInstance().getRegistrationID(object : TIMPushCallback<Any?>() { override fun onSuccess(data: Any?) { Log.d("TIMPush", ">>>>> getRegistrationID success, registrationID = $data") } override fun onError(errCode: Int, errMsg: String?, data: Any?) { Log.e("TIMPush", ">>>>> getRegistrationID failed, errCode = $errCode, errMsg = $errMsg") } }) } override fun onError(errCode: Int, errMsg: String?, data: Any?) { Log.e("TIMPush", ">>>>> registerPush failed, errCode = $errCode, errMsg = $errMsg") } })}

如触发 onError，可按 错误码 查询 code 含义。

21、步骤5：测试推送链路

完成上述集成步骤后，需要通过发送测试消息验证链路是否打通，请确认：

1. Android 13 及以上已允许通知权限；

2. Android 8.0 及以上目标通知渠道已开启（包括横幅、锁屏、声音开关）；

3. App 已置于后台或杀进程。

发送测试消息可以采用下面几种方法：

控制台发送REST API 发送SDK API 发送仅集成 TIMPush 的用户，建议优先使用腾讯云控制台接入测试能力验证离线推送。操作路径：腾讯云控制台 > 推送服务 Push > 接入测试。在接入测试页面，可以指定 registrationID 发送离线推送测试。如果需要通过服务端发送推送，可参考 全员/标签推送。如果你的项目已接入 IM SDK，可在调用 sendMessage 发送消息时，通过 V2TIMOfflinePushInfo 设置离线推送参数。示例：V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();pushInfo.setTitle("推送标题");pushInfo.setDesc("推送内容");pushInfo.setExt("业务自定义 ext".getBytes());V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, userID, null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, pushInfo, new V2TIMSendCallback<V2TIMMessage>() { @Override public void onProgress(int progress) {} @Override public void onError(int code, String desc) { Log.e("TIMPush", ">>>>> sendMessage failed, code = " + code + ", desc = " + desc); } @Override public void onSuccess(V2TIMMessage message) { Log.d("TIMPush", ">>>>> sendMessage success, msgID = " + message.getMsgID()); } });sendMessage 属于 IMSDK 消息发送能力。仅集成 TIMPush 的用户不需要为了验证离线推送而额外接入完整 Chat 初始化、登录和消息发送流程。

如果要实现自定义点击 Push 消息跳转，参考文档 自定义点击推送跳转 处理。

22、接入排查

如果接入完成收不到推送，请使用 排查工具 查看具体原因。排查后依然异常，请 联系我们 提交反馈。