即时通信 IM Android

本文将介绍如何在 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'
}
步骤3：集成厂商通道 SDK
小米
华为
OPPO
vivo
荣耀
魅族
Google FCM
在应用模块 build.gradle 的 dependencies 中追加小米通道包：
implementation 'com.tencent.timpush:xiaomi:latest'
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'
在应用模块 build.gradle 的 dependencies 中追加 OPPO 通道包：
implementation 'com.tencent.timpush:oppo:latest'
1. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 的 dependencies 中追加 vivo 通道包：
implementation 'com.tencent.timpush:vivo:latest'
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'
4. 配置 manifestPlaceholders 和 AndroidManifest.xml
在 manifestPlaceholders 或 AndroidManifest.xml 中配置 meta-data。
方法 1：配置 manifestPlaceholders
方法 2：配置 AndroidManifest.xml
android {
    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'
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'
厂商消息分类机制会影响消息推送的及时性，参考文档 厂商消息分类限制和使用指南 处理。
步骤4：注册推送服务
调用 registerPush
﻿registerPush 用于向腾讯云 Push 后台注册当前设备的推送 token。请在用户同意隐私政策后调用 registerPush(appKey = Push Key)，示例代码如下所示：
Java
Kotlin
import 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.Log
import com.tencent.timpush.TIMPushCallback
import 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 含义。
步骤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 消息跳转，参考文档 自定义点击推送跳转 处理。
接入排查
如果接入完成收不到推送，请使用 排查工具 查看具体原因。排查后依然异常，请 联系我们 提交反馈。
Android

本页目录：

前提条件

方式1：AI 集成

方式2：手动集成

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

步骤2：集成 TIMPush SDK

步骤3：集成厂商通道 SDK

1. 添加厂商配置文件

2. 配置 Gradle 插件

追加厂商 Maven 仓库

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

1. 集成 TIMPush 厂商依赖

2. 配置 manifestPlaceholders 和 AndroidManifest.xml

1. 添加厂商配置文件

2. 配置 Gradle 插件

追加厂商 Maven 仓库

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

4. 配置 manifestPlaceholders 和 AndroidManifest.xml

1. 添加厂商配置文件

2. 配置 Gradle 插件

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

步骤4：注册推送服务

调用 registerPush

步骤5：测试推送链路

接入排查
