即时通信 IM Android

本文将介绍如何在 Android 工程中集成 TIMPush。
前提条件
请确认已 开通 Push 服务 并按需完成 Android 厂商配置（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / Google FCM），获取到了下列信息：
资源
获取位置
用途
SDKAppID
腾讯云控制台 > 推送服务 Push > 概览
调用 registerPush 注册推送服务。
客户端密钥
腾讯云控制台 > 推送服务 Push > 概览 > 客户端密钥
调用 registerPush 注册推送服务。Push 的客户端密钥和 Chat 的客户端密钥不同，请勿混用。
timpush-configs.json
腾讯云控制台下载
放入 Android 应用模块的 assets 目录，TIMPush 注册时会读取该配置文件。
Android 工程包名
Android 工程 applicationId
需要与厂商平台应用包名保持一致。
目标厂商配置
对应厂商配置文档
确认厂商侧已开通推送服务，并已在腾讯云控制台添加厂商证书。
厂商配置文件
厂商开放平台
华为、荣耀、Google FCM 需要将对应 JSON 配置文件添加到工程中。
测试真机
目标厂商设备
厂商通道建议使用对应厂商真机验证。设备厂商与配置厂商不一致时，验证结果可能误导。
TIMPush 版本号 VERSION
﻿更新日志﻿
Gradle 依赖版本。本文使用 VERSION 占位，请替换为实际版本号。建议使用最新版本；如使用 7.7.5283 以下版本，荣耀通道配置可能有差异。
本文示例中的 VERSION、SDKAppID、AppKey、厂商 AppID、厂商 AppKey 均为占位符，请勿在代码仓库中提交真实密钥。
AI 集成
通过 npx 安装 @tencent-rtc/trtc-push-skill 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，您可以直接向 AI 输入“集成 Android 离线推送”等需求，AI 将根据项目类型引导您完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。详情可参考 AI Coding。
手动集成
步骤1：集成 TIMPush SDK
下载并添加 TIMPush 配置文件
在腾讯云控制台下载 timpush-configs.json，下载路径为：控制台 > 推送服务 Push > 推送设置 > 厂商配置 > 下载证书，示意图为：
﻿
下载后，将该文件添加到应用模块的 assets 目录。推荐存储路径：app/src/main/assets/timpush-configs.json，其中 app 是您项目的应用模块，可替换成实际名称。如果工程中没有 assets 目录，请在 src/main/ 下手动创建。
注意：
TIMPush 注册推送时会读取该文件中的厂商证书配置，不要放在 MainActivity 同级目录、工程根目录或 res 目录。如果文件缺失或放错目录，SDK 无法获得对应厂商通道配置，可能导致注册或收消息失败。
配置 Gradle 仓库
配置仓库的目的是让 Gradle 能下载 TIMPush 及相关依赖。本节只配置与厂商无关的公共仓库：google()、mavenCentral() 用于解析 Android 官方组件，腾讯云 Maven 仓库用于解析 TIMPush 等腾讯云依赖。
Android 工程可能使用 Groovy DSL 或 Kotlin DSL，请先根据文件后缀判断当前工程使用的 DSL 类型：
文件
DSL 类型
settings.gradle、build.gradle
Groovy DSL
settings.gradle.kts、build.gradle.kts
Kotlin DSL
请根据工程使用的 Gradle 版本选择配置位置。如果不确定工程使用的 Gradle 版本，可在项目根目录 gradle/wrapper/gradle-wrapper.properties 中查看 distributionUrl 对应的版本号。
注意：
不要把 Groovy 示例直接复制到 .kts 文件中。Kotlin DSL 使用双引号、括号和 uri(...) 写法。
Gradle 7.1 及以上版本
Gradle 7.0 版本
Gradle 7.0 以下版本
在项目级 settings.gradle（Groovy DSL）或 settings.gradle.kts（Kotlin DSL）中，同时在 pluginManagement > repositories 和 dependencyResolutionManagement > repositories 中添加仓库。
Groovy DSL (settings.gradle)
Kotlin DSL (settings.gradle.kts)
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
﻿
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
        maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public/") }
    }
}
﻿
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public/") }
    }
}
Gradle 7.0 版本通常使用 Groovy DSL。如您的工程使用 Kotlin DSL，请将单引号改为双引号，url "..." 改为 url = uri("...")。
1. 在项目级 build.gradle 的 buildscript > repositories 中添加插件仓库。
buildscript {
    repositories {
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
2. 在 settings.gradle 的 dependencyResolutionManagement > repositories 中添加依赖仓库。
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
Gradle 7.0 以下版本通常使用 Groovy DSL。如您的工程使用 Kotlin DSL，请将单引号改为双引号，url "..." 改为 url = uri("...")。
在项目级 build.gradle 的 buildscript > repositories 和 allprojects > repositories 中添加仓库。
buildscript {
    repositories {
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
﻿
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
}
集成 TIMPush 基础依赖
在应用模块的 build.gradle 或 build.gradle.kts 中添加 TIMPush 基础依赖。基础包提供 TIMPush 注册、监听和通用能力。
下方示例中的 VERSION 均指 TIMPush SDK 的版本号（如 8.9.7537），不是 Android 系统版本或厂商 SDK 版本。获取最新版本号请查看更新日志。
Groovy DSL
Kotlin DSL
dependencies {
    implementation 'com.tencent.timpush:timpush:VERSION'
    implementation 'com.tencent.liteav.tuikit:tuicore:VERSION'
}
dependencies {
    implementation("com.tencent.timpush:timpush:VERSION")
    implementation("com.tencent.liteav.tuikit:tuicore:VERSION")
}
添加依赖后，请在 Android Studio 中单击 Sync Now，或选择 File > Sync Project with Gradle Files 触发 Gradle 同步。
注意：
TIMPush、TUICore 和各厂商通道包建议使用相同 VERSION，避免依赖冲突。项目已接入 IM SDK 或 TUIKit 时，也需要确认相关 SDK 版本兼容。
验证：Gradle Sync 成功完成，无报错。如果报依赖找不到，请检查 VERSION 是否正确、腾讯云 Maven 仓库是否缺失。
设置混淆规则
如果应用开启了代码混淆，请在 proguard-rules.pro 中加入 TIMPush 相关类不混淆规则。该配置用于避免 Release 包中 TIMPush 相关类、回调或厂商适配逻辑被混淆后无法正常调用：
-keep class com.tencent.qcloud.** { *; }
-keep class com.tencent.timpush.** { *; }
完成后，请重新构建 Release 包，并在真机上验证注册和收消息链路。
验证：App 可在目标厂商真机上正常安装和启动，无崩溃。如果启动崩溃，请检查 Application 声明、配置文件位置和 Manifest 合并错误。同时确认测试真机厂商与目标厂商通道一致（如不要在华为设备上验证荣耀通道）。
步骤2：集成厂商通道 SDK
请按目标厂商页签配置对应通道。只集成某个厂商时，只添加该厂商需要的配置文件、插件和依赖即可。
小米
华为
OPPO
vivo
荣耀
魅族
Google FCM
前置
请先完成 小米厂商配置，并确认：
已在腾讯云控制台添加小米厂商证书；
已重新下载包含小米证书的 timpush-configs.json，并放入应用模块 assets 目录；
使用小米真机验证。
1. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加小米通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:xiaomi:VERSION'
implementation("com.tencent.timpush:xiaomi:VERSION")
集成结果判断：Gradle Sync 成功完成，无报错。
2. 配置消息触达统计（可选）
小米通道当前无需在客户端额外配置回执地址。如需统计，请按 小米厂商配置 完成控制台侧配置。
3. 配置消息分类（可选）
发送离线推送时可通过 SDK API 设置小米渠道 ID，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidXiaoMiChannelID(String channelID) 设置小米渠道 channelID：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidXiaoMiChannelID("your_xiaomi_channel_id");
前置
请先完成 华为厂商配置，并确认：
已在腾讯云控制台添加华为厂商证书；
已重新下载包含华为证书的 timpush-configs.json，并放入应用模块 assets 目录；
测试包当前签名（debug 或 release）的 SHA-256 已在华为控制台 项目设置 > 常规 > SHA 证书指纹 中添加，指纹不一致会报 6003: certificate fingerprint error；
使用华为真机验证。
1. 添加厂商配置文件
在华为 AppGallery Connect 下载 agconnect-services.json，添加到应用模块根目录（与应用模块的 build.gradle / build.gradle.kts 同级）：
app/agconnect-services.json
修改项目、应用信息、证书指纹或服务配置后，建议重新下载并替换。后续构建时，华为 AGConnect 插件会读取该文件并将厂商要求的资源、Manifest 信息合并进应用包。
2. 配置 Gradle 插件
华为需要通过 AGConnect Gradle 插件在构建期读取 agconnect-services.json，并依赖华为 Maven 仓库解析插件与 SDK。
追加厂商 Maven 仓库
请在已添加的公共仓库基础上追加华为仓库。
Gradle 7.1 及以上
Gradle 7.0 及以下
在 settings.gradle 或 settings.gradle.kts 的 pluginManagement > repositories 和 dependencyResolutionManagement > repositories 中追加：
Groovy DSL
Kotlin DSL
maven { url "https://developer.huawei.com/repo/" }
maven { url = uri("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 及以下
Gradle 7.1 及以上项目通常在 settings.gradle 中配置依赖仓库。由于华为插件通过 buildscript > dependencies > classpath 声明，还需要在项目级 build.gradle 或 build.gradle.kts 的 buildscript > repositories 中包含 google() 和华为仓库，否则可能出现插件 classpath 依赖解析失败。
如果项目级 build.gradle.kts 已通过 plugins {} 块声明 AGP，原有 plugins {} 块保留不动，在 dependencies 中声明 com.android.tools.build:gradle 即可。如果项目同时使用 Kotlin Android 插件，也请声明 org.jetbrains.kotlin:kotlin-gradle-plugin。
Groovy DSL（build.gradle）
Kotlin DSL（build.gradle.kts）
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'
    }
}
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public/") }
        maven { url = uri("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。如果项目级 plugins {} 块中已经声明了 com.android.application 版本，两个位置的 AGP 版本需要保持一致。
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 或 build.gradle.kts 中启用华为插件。应用模块通常为 app。
如果应用模块中已经存在 plugins 块，请在现有 plugins 块中追加，不要重复添加已有的 com.android.application 插件。
Groovy DSL（app/build.gradle）
Kotlin DSL（app/build.gradle.kts）
plugins {
    // 华为 AGConnect。
    id 'com.huawei.agconnect'
}
// 或：apply plugin: 'com.huawei.agconnect'
plugins {
    // 华为 AGConnect。
    id("com.huawei.agconnect")
}
// 或：apply(plugin = "com.huawei.agconnect")
完成配置后，请在 Android Studio 中单击 Sync Now，或选择 File > Sync Project with Gradle Files 触发 Gradle 同步。同步成功后，再执行构建验证。
3. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加华为通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:huawei:VERSION'
implementation("com.tencent.timpush:huawei:VERSION")
集成结果判断：Gradle Sync 成功完成，无报错；确认 agconnect-services.json 已放在应用模块根目录。
4. 配置消息触达统计（可选）
如需统计触达或点击数据，请配置回执地址 https://api.im.qcloud.com/v3/offline_push_report/huawei。华为推送证书 ID <= 11344 时使用华为推送 v2 接口，不支持触达和点击回执；如需支持统计，请重新生成并更新证书 ID。回执地址不配置或配置错误，都会影响触达统计。
5. 配置消息分类（可选）
发送离线推送时可通过 SDK API 设置华为消息分类，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidHuaWeiCategory(String category) 设置华为推送消息分类：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidHuaWeiCategory("IM");
前置
请先完成 OPPO 厂商配置，并确认：
已在腾讯云控制台添加 OPPO 厂商证书；
已重新下载包含 OPPO 证书的 timpush-configs.json，并放入应用模块 assets 目录；
使用 OPPO 真机验证。
1. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加 OPPO 通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:oppo:VERSION'
implementation("com.tencent.timpush:oppo:VERSION")
集成结果判断：Gradle Sync 成功完成，无报错。
2. 配置消息触达统计（可选）
OPPO 通道当前无需在客户端额外配置回执地址。如需统计，请按 OPPO 厂商配置 完成控制台侧配置。
3. 配置消息分类（可选）
OPPO 同时存在新规则和旧规则，不要混用。
新规则：适用于新接入应用，或按 OPPO 新消息分类改造的应用。使用 category、私信模板参数，以及可选的 notify_level。
旧规则：仅适用于此前已开通 OPPO 私信通道权限的存量应用，使用已创建并在 OPPO 推送运营后台登记的私信通道 ChannelID。
只有 IM 聊天、订单、交易、账号变更等用户预期强、需要及时触达的消息，才建议申请或使用高优先级分类。营销、广告、活动、资讯类消息不应滥用高优分类，否则可能被厂商降级、限频或冻结权限。
发送离线推送时可通过 SDK API 设置，API 设置优先级通常高于控制台证书默认配置。
OPPO 新规则配置
OPPO 新接入应用建议使用新消息分类规则。IM 聊天、音视频通话等需要及时触达的消息，通常使用 category=IM，并按 OPPO 要求申请通讯与服务不限量权益或私信模板。
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
﻿
// New OPPO message classification rule. Use IM for chat and call messages.
pushInfo.setAndroidOPPOCategory("IM");
﻿
// Optional. 1 = notification bar, 2 = notification bar + lock screen + sound + vibration.
// Use 16 only after OPPO strong reminder capability is approved.
pushInfo.setAndroidOPPONotifyLevel(2);
对应 API：
﻿setAndroidOPPOCategory(String category)：设置 OPPO 新消息分类，例如 IM 消息使用 IM。
﻿setAndroidOPPONotifyLevel(int level)：设置 OPPO 通知栏消息提醒等级。使用前需要先设置 category；如需 16，需先向 OPPO 申请强提醒能力。
如需使用 OPPO 私信模板，可通过 V2TIMOfflinePushInfo.setVendorParams(String vendorParams) 携带厂商扩展参数。根据腾讯云离线推送消息属性设置文档，vendorParams 是 JSON 字符串，且 oppoTitleParam、oppoContentParam 等字段本身也需要序列化为 JSON 字符串。
Map<String, Object> vendorParams = new HashMap<>();
vendorParams.put("oppoTemplateId", "OPPO 私信模板 ID");
﻿
Map<String, Object> titleParams = new HashMap<>();
titleParams.put("title", "推送标题");
vendorParams.put("oppoTitleParam", new Gson().toJson(titleParams));
﻿
Map<String, Object> contentParams = new HashMap<>();
contentParams.put("desc", "推送内容");
vendorParams.put("oppoContentParam", new Gson().toJson(contentParams));
﻿
pushInfo.setVendorParams(new Gson().toJson(vendorParams));
vendorParams 扩展参数能力要求 IMSDK 8.7 及以上版本。oppoTemplateId 必须是 OPPO 私信申请得到的模板 ID，不支持开发者自拟。oppoTitleParam 和 oppoContentParam 中的 key 需要与 OPPO 模板中的占位符一致。
OPPO 旧规则配置
旧规则仅适用于此前已开通 OPPO 私信通道权限的存量应用。如果应用仍按旧规则使用私信通道，请确保客户端创建的通道 ID 已在 OPPO 推送运营后台登记，并与发送离线推送时设置的 channelID 保持一致。
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
﻿
// Old OPPO private channel rule for existing apps only.
pushInfo.setAndroidOPPOChannelID("your_oppo_private_channel_id");
新接入应用不要把 setAndroidOPPOChannelID 当作 OPPO 新消息分类的必配项。新规则优先使用 setAndroidOPPOCategory，并按需配置 setVendorParams 和 setAndroidOPPONotifyLevel。
前置
请先完成 vivo 厂商配置，并确认：
已在腾讯云控制台添加 vivo 厂商证书；
已重新下载包含 vivo 证书的 timpush-configs.json，并放入应用模块 assets 目录；
使用 vivo 真机验证。
1. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加 vivo 通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:vivo:VERSION'
implementation("com.tencent.timpush:vivo:VERSION")
2. 配置 manifestPlaceholders 和 AndroidManifest.xml
vivo 需要将厂商分配的 AppID / AppKey 配置到清单文件中。厂商 SDK 会从 Manifest 中读取这些值来识别当前应用；缺失或填写错误可能导致编译失败或厂商注册失败。您可以选择 manifestPlaceholders 或直接在 AndroidManifest.xml 中配置 meta-data。
方法 1：配置 manifestPlaceholders
方法 2：配置 AndroidManifest.xml
在 manifestPlaceholders 里添加条目：
Groovy DSL
Kotlin DSL
android {
    defaultConfig {
        manifestPlaceholders = [
            "VIVO_APPKEY": "您应用分配的证书 APPKEY",
            "VIVO_APPID" : "您应用分配的证书 APPID"
        ]
    }
}
android {
    defaultConfig {
        manifestPlaceholders["VIVO_APPKEY"] = "您应用分配的证书 APPKEY"
        manifestPlaceholders["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>
集成结果判断：Gradle Sync 成功完成，无报错。
3. 配置消息触达统计（可选）
如需统计触达或点击数据，请配置回执地址 https://api.im.qcloud.com/v3/offline_push_report/vivo，并按控制台要求配置回执 ID。回执地址不配置或配置错误，都会影响触达统计。
4. 配置消息分类（可选）
发送离线推送时可通过 SDK API 设置 vivo 消息类别，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidVIVOCategory(String category) 设置 vivo 推送消息类别：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidVIVOCategory("IM");
前置
请先完成 荣耀厂商配置，并确认：
已在腾讯云控制台添加荣耀厂商证书；
已重新下载包含荣耀证书的 timpush-configs.json，并放入应用模块 assets 目录；
测试包当前签名（debug 或 release）的 SHA-256 已在荣耀控制台 项目设置 > 常规 > SHA 证书指纹 中添加，指纹不一致会报 6003: certificate fingerprint error；
使用荣耀真机验证。不要在华为设备上验证荣耀通道。
1. 添加厂商配置文件
在荣耀开发者服务平台下载 mcs-services.json，添加到应用模块根目录（与应用模块的 build.gradle / build.gradle.kts 同级）：
app/mcs-services.json
修改项目、应用信息或开发服务设置后，需要重新下载并替换。后续构建时，荣耀插件会读取该文件并将厂商要求的资源、Manifest 信息合并进应用包。
2. 配置 Gradle 插件
荣耀需要通过 com.hihonor.mcs:asplugin 在构建期读取 mcs-services.json，并依赖荣耀 Maven 仓库解析插件与 SDK。荣耀官方示例统一使用 buildscript > dependencies > classpath 形式，未提供 plugins {} 块写法。
追加厂商 Maven 仓库
请在「配置 Gradle 仓库」已添加的公共仓库基础上，追加荣耀仓库。
Gradle 7.1 及以上
Gradle 7.0 及以下
在 settings.gradle 或 settings.gradle.kts 的 pluginManagement > repositories 和 dependencyResolutionManagement > repositories 中追加：
Groovy DSL
Kotlin DSL
maven { url "https://developer.hihonor.com/repo" }
maven { url = uri("https://developer.hihonor.com/repo") }
在项目级 build.gradle 的 buildscript > repositories，以及 settings.gradle 的 dependencyResolutionManagement > repositories（Gradle 7.0）或 allprojects > repositories（Gradle 7.0 以下）中追加：
maven { url "https://developer.hihonor.com/repo" }
配置项目级插件依赖
Gradle 7.1 及以上
Gradle 7.0 及以下
如果项目级 build.gradle.kts 已通过 plugins {} 块声明 AGP（新建 Kotlin DSL 项目的默认方式），原有 plugins {} 块保留不动，不需要整体迁移到 buildscript 写法。由于荣耀官方示例统一使用 buildscript > dependencies > classpath 声明 asplugin，请在项目级 Gradle 文件中额外补充 buildscript 配置，并在 dependencies 中声明 com.android.tools.build:gradle。如果项目同时使用 Kotlin Android 插件，也请声明 org.jetbrains.kotlin:kotlin-gradle-plugin。
Groovy DSL（build.gradle）
Kotlin DSL（build.gradle.kts）
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'
    }
}
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public/") }
        maven { url = uri("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 版本，例如 8.9.1。如果项目级 plugins {} 块中已经声明了 com.android.application 版本，两个位置的 AGP 版本需要保持一致。
2. 请将<KOTLIN_VERSION> 替换为项目当前使用的 Kotlin Gradle Plugin 版本；如果项目未使用 Kotlin Android 插件，可删除该行。
在项目级 build.gradle 的 buildscript > dependencies 中追加：
classpath 'com.hihonor.mcs:asplugin:2.0.1.300'
在应用模块启用插件
完成项目级插件依赖配置后，还需要在应用模块的 build.gradle 或 build.gradle.kts 中启用荣耀插件。应用模块通常为 app。
如果应用模块中已经存在 plugins 块，请在现有 plugins 块中追加，不要重复添加已有的 com.android.application 插件。应用级 plugins { id("com.hihonor.mcs.asplugin") } 可省略版本号（由项目级 classpath 提供），或改写为 apply plugin。
Groovy DSL（app/build.gradle）
Kotlin DSL（app/build.gradle.kts）
plugins {
    // 荣耀 Push。
    id 'com.hihonor.mcs.asplugin'
}
// 或：apply plugin: 'com.hihonor.mcs.asplugin'
plugins {
    // 荣耀 Push。
    id("com.hihonor.mcs.asplugin")
}
// 或：apply(plugin = "com.hihonor.mcs.asplugin")
完成配置后，请在 Android Studio 中单击 Sync Now，或选择 File > Sync Project with Gradle Files 触发 Gradle 同步。
3. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加荣耀通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:honor:VERSION'
implementation("com.tencent.timpush:honor:VERSION")
4. 配置 manifestPlaceholders 和 AndroidManifest.xml
荣耀需要将厂商分配的 AppID 配置到清单文件中。厂商 SDK 会从 Manifest 中读取该值来识别当前应用；缺失或填写错误可能导致编译失败或厂商注册失败。您可以选择 manifestPlaceholders 或直接在 AndroidManifest.xml 中配置 meta-data。
方法 1：配置 manifestPlaceholders
方法 2：配置 AndroidManifest.xml
Groovy DSL
Kotlin DSL
android {
    defaultConfig {
        manifestPlaceholders = [
            "HONOR_APPID": "您应用分配的证书 APPID"
        ]
    }
}
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>
集成结果判断：Gradle Sync 成功完成，无报错；确认 mcs-services.json 已放在应用模块根目录。
5. 配置消息触达统计（可选）
如需统计触达或点击数据，请配置回执地址 https://api.im.qcloud.com/v3/offline_push_report/honor。回执地址不配置或配置错误，都会影响触达统计。
6. 配置消息分类（可选）
发送离线推送时可通过 SDK API 设置荣耀消息分类，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidHonorImportance(String importance) 设置荣耀消息分类，NORMAL 表示服务通讯类消息，LOW 表示资讯营销类消息：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidHonorImportance("NORMAL");
前置
请先完成 魅族厂商配置，并确认：
已在腾讯云控制台添加魅族厂商证书；
已重新下载包含魅族证书的 timpush-configs.json，并放入应用模块 assets 目录；
使用魅族真机验证。
1. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加魅族通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:meizu:VERSION'
implementation("com.tencent.timpush:meizu:VERSION")
集成结果判断：Gradle Sync 成功完成，无报错。
2. 配置消息触达统计（可选）
如需统计触达或点击数据，请打开回执开关并配置回执地址 https://api.im.qcloud.com/v3/offline_push_report/meizu。回执地址不配置或配置错误，都会影响触达统计。
3. 配置消息分类（可选）
发送离线推送时可通过 SDK API 设置魅族消息分类，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidMeizuNotifyType(int type) 设置魅族消息分类，0 表示公信消息，1 表示私信消息：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidMeizuNotifyType(1);
前置
请先完成 Google FCM 厂商配置，并确认：
已在腾讯云控制台添加 FCM 厂商证书；
已重新下载包含 FCM 证书的 timpush-configs.json，并放入应用模块 assets 目录；
测试设备具备可用的 Google Play 服务（国内无 GMS 的设备无法验证 FCM 通道）。
1. 添加厂商配置文件
在 Firebase 控制台下载 google-services.json，添加到应用模块根目录（与应用模块的 build.gradle / build.gradle.kts 同级）：
app/google-services.json
后续构建时，Google Services 插件会读取该文件并将 FCM 要求的资源、Manifest 信息合并进应用包。
2. 配置 Gradle 插件
Google FCM 需要通过 Google Services Gradle 插件在构建期读取 google-services.json。请按工程 Gradle 版本选择配置方式。FCM 无需额外的厂商 Maven 仓库，相关依赖通过 google() 仓库解析。
配置项目级插件依赖
Gradle 7.1 及以上
Gradle 7.0 及以下
Gradle 7.1 及以上项目通常在 settings.gradle 或 settings.gradle.kts 中配置依赖仓库。由于 Google Services 插件通过 buildscript > dependencies > classpath 声明，还需要在项目级 build.gradle 或 build.gradle.kts 的 buildscript > repositories 中包含 google() 等仓库，否则可能出现插件 classpath 依赖解析失败。
如果项目级 build.gradle.kts 已通过 plugins {} 块声明 AGP（新建 Kotlin DSL 项目的默认方式），原有 plugins {} 块保留不动，不需要整体迁移到 buildscript 写法，在 dependencies 中声明 com.android.tools.build:gradle 即可。如果项目同时使用 Kotlin Android 插件，也请声明 org.jetbrains.kotlin:kotlin-gradle-plugin。
Groovy DSL（build.gradle）
Kotlin DSL（build.gradle.kts）
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'
    }
}
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = uri("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 版本，例如 8.9.1。如果项目级 plugins {} 块中已经声明了 com.android.application 版本，两个位置的 AGP 版本需要保持一致。
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 或 build.gradle.kts 中启用 Google Services 插件。应用模块通常为 app。
如果应用模块中已经存在 plugins 块，请在现有 plugins 块中追加，不要重复添加已有的 com.android.application 插件。
Groovy DSL（app/build.gradle）
Kotlin DSL（app/build.gradle.kts）
plugins {
    // Google FCM。
    id 'com.google.gms.google-services'
}
// 或：apply plugin: 'com.google.gms.google-services'
plugins {
    // Google FCM。
    id("com.google.gms.google-services")
}
// 或：apply(plugin = "com.google.gms.google-services")
完成配置后，请在 Android Studio 中单击 Sync Now，或选择 File > Sync Project with Gradle Files 触发 Gradle 同步。同步成功后，再执行构建验证。
3. 集成 TIMPush 厂商依赖
在应用模块 build.gradle 或 build.gradle.kts 的 dependencies 中追加 FCM 通道包，VERSION 与基础包保持一致：
Groovy DSL
Kotlin DSL
implementation 'com.tencent.timpush:fcm:VERSION'
implementation("com.tencent.timpush:fcm:VERSION")
集成结果判断：Gradle Sync 成功完成，无报错；确认 google-services.json 已放在应用模块根目录。
4. 配置消息触达统计（可选）
FCM 暂不支持推送统计功能。
5. 配置消息分类（可选）
Android 8.0 及以上可通过通知渠道 ID 控制 FCM 通知展示策略。渠道创建与配置见 Google FCM 厂商配置。发送离线推送时可通过 SDK API 设置，API 设置优先级通常高于控制台证书默认配置。调用 setAndroidFCMChannelID(String channelID) 设置 FCM 通道通知渠道 ID：
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setAndroidFCMChannelID("your_fcm_channel_id");
警告：
请关注各厂商通道消息分类规则：
厂商离线通道的消息分类机制会影响推送及时性、单设备每日接收数量、夜间展示、声音、横幅和厂商通道权限。
只有 IM 聊天、订单、交易、账号变更等用户预期强、需要及时触达的消息，才建议申请或使用高优先级分类。营销、广告、活动、资讯类消息不应滥用高优分类，否则可能被厂商降级、限频或冻结权限。
发送离线推送时，API 设置优先级高于腾讯云控制台证书默认配置。
步骤3：注册推送服务
调用 registerPush
﻿registerPush 用于向 TIMPush 注册当前设备的推送 token。注册成功后，TIMPush 会为当前设备建立一个推送目标标识 registrationID；服务端、控制台接入测试和排查工具可以使用该标识向这台设备下发离线推送。若 App 同时接入 IM 并完成登录，也可以使用 userID 向该用户已建立推送关系的设备下发离线推送。
appKey 的取值会影响注册方式和可用的推送标识：
appKey = Push Key：注册 TIMPush 独立推送能力。Push Key 客户端密钥。
appKey = null：复用 IM 登录态注册推送，必须在 IM login 成功后调用。
请先根据业务场景确认调用顺序：
场景
调用顺序
服务端可用于发送推送的目标标识
说明
仅使用 TIMPush
App 每次冷启动后调用
registerPush（appKey = Push Key）
registrationID
适用于营销 / 活动 / 通知推送，不接入 IM SDK。
IM SDK + TIMPush
先注册 Push 再登录
registerPush(appKey = Push Key)
→ IM login
登录前：registrationID；
登录后：registrationID + userID
适用于希望用户未登录时也能收到营销推送的场景。
IM SDK + TIMPush
先登录再注册 Push
IM login
→ registerPush(appKey = null)
登录后：userID
注册后：userID + registrationID，
此时 registrationID = userID
适用于希望用户登录后能收到 Chat 离线消息和营销推送的场景。
注意：
如果用户退出 IM SDK，同时集成了 IM SDK + TIMPush 的场景下已建立的 userID 与 registrationID 推送关系都会失效，需要重新完成对应注册。
Chat 应用的密钥仅用于 IM 登录，不能作为 registerPush 的 appKey。
App 冷启动注册 TIMPush（appKey 传 Push Key）
IM 登录后注册推送（appKey 传 null）
App 冷启动、用户同意隐私政策后调用 registerPush(appKey = Push Key)。如果工程已有自定义 Application，将注册逻辑放在该类中；如果没有，需新建并在 AndroidManifest.xml 中声明。
建议在 registerPush 成功回调里调用 getRegistrationID 打印 registrationID，方便后续根据 registrationID 发送离线推送消息。
Java
Kotlin
import android.app.Application;
import android.util.Log;
import com.tencent.timpush.TIMPushCallback;
import com.tencent.timpush.TIMPushManager;
﻿
public class App extends Application {
    private static final String TAG = "TIMPush";
﻿
    @Override
    public void onCreate() {
        super.onCreate();
        registerTIMPush();
    }
﻿
    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(TAG, ">>>>> registerPush success, data = " + data);
                // 获取并打印出 registrationID，方便后续根据 registrationID 发送离线推送消息
                TIMPushManager.getInstance().getRegistrationID(new TIMPushCallback<Object>() {
                    @Override
                    public void onSuccess(Object data) {
                        String registrationID = (String) data;
                        Log.d(TAG, ">>>>> getRegistrationID success, registrationID = " + registrationID);
                    }
                    @Override
                    public void onError(int errCode, String errMsg, Object data) {
                        Log.e(TAG, ">>>>> getRegistrationID failed, errCode = " + errCode
                                + ", errMsg = " + errMsg);
                    }
                });
            }
﻿
            @Override
            public void onError(int errCode, String errMsg, Object data) {
                Log.e(TAG, ">>>>> registerPush failed, errCode = " + errCode
                        + ", errMsg = " + errMsg);
            }
        });
    }
}
import android.app.Application
import android.util.Log
import com.tencent.timpush.TIMPushCallback
import com.tencent.timpush.TIMPushManager
﻿
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        registerTIMPush()
    }
﻿
    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")
            }
        })
    }
}
在 AndroidManifest.xml 中声明 Application：
<application
    android:name=".App"
    ...>
</application>
请在 IM login 成功回调中调用 registerPush(appKey = null)。建议在 registerPush 成功回调里调用 getRegistrationID 打印 registrationID，方便后续根据 registrationID 发送离线推送消息。
Java
Kotlin
import android.content.Context;
import android.util.Log;
﻿
import com.tencent.imsdk.v2.V2TIMCallback;
import com.tencent.imsdk.v2.V2TIMManager;
import com.tencent.imsdk.v2.V2TIMSDKConfig;
import com.tencent.qcloud.tim.push.TIMPushCallback;
import com.tencent.qcloud.tim.push.TIMPushManager;
﻿
public void loginIMAndRegisterPush(Context context) {
    int sdkAppId = 0; // TODO: Replace with your SDKAppID.
    String userID = "<YOUR_USER_ID>";
    String userSig = "<YOUR_USER_SIG>";
﻿
    boolean initSuccess = V2TIMManager.getInstance().initSDK(context, sdkAppId, new V2TIMSDKConfig());
    if (!initSuccess) {
        Log.e("TIMPush", ">>>>> IM SDK init failed");
        return;
    }
﻿
    V2TIMManager.getInstance().login(userID, userSig, new V2TIMCallback() {
        @Override
        public void onSuccess() {
            TIMPushManager.getInstance().registerPush(context, sdkAppId, null, 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(TAG, ">>>>> getRegistrationID success, registrationID = " + registrationID);
                        }
                        @Override
                        public void onError(int errCode, String errMsg, Object data) {
                            Log.e(TAG, ">>>>> 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);
                }
            });
        }
﻿
        @Override
        public void onError(int code, String desc) {
            Log.e("TIMPush", ">>>>> IM login failed, code = " + code + ", desc = " + desc);
        }
    });
}
import android.content.Context
import android.util.Log
import com.tencent.imsdk.v2.V2TIMCallback
import com.tencent.imsdk.v2.V2TIMManager
import com.tencent.imsdk.v2.V2TIMSDKConfig
import com.tencent.qcloud.tim.push.TIMPushCallback
import com.tencent.qcloud.tim.push.TIMPushManager
﻿
fun loginIMAndRegisterPush(context: Context) {
    val sdkAppId = 0 // TODO: Replace with your SDKAppID.
    val userID = "<YOUR_USER_ID>"
    val userSig = "<YOUR_USER_SIG>"
﻿
    val initSuccess = V2TIMManager.getInstance().initSDK(context, sdkAppId, V2TIMSDKConfig())
    if (!initSuccess) {
        Log.e("TIMPush", ">>>>> IM SDK init failed")
        return
    }
﻿
    V2TIMManager.getInstance().login(userID, userSig, object : V2TIMCallback {
        override fun onSuccess() {
            TIMPushManager.getInstance().registerPush(context, sdkAppId, null, 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")
                }
            })
        }
﻿
        override fun onError(code: Int, desc: String?) {
            Log.e("TIMPush", ">>>>> IM login failed, code = $code, desc = $desc")
        }
    })
}
警告：
如果您的业务仅使用即时通信 IM 聊天能力，请勿在 IM 登录前先调用 registerPush。否则 SDK 可能会按独立推送场景注册 Push 类型账号，并产生对应的 Push DAU。Push DAU 超出套餐额度后，可能会产生额外费用。
验证：
1. registerPush 的 onSuccess 回调被触发。
2. 登录腾讯云控制台 > 即时通信 IM > 推送服务 Push > 推送排查，按当前场景输入 registrationID 或 userID，确认 token 已上传。
3. 如触发 onError，可按 错误码 查询 code 含义。
自定义 registrationID（可选）
如需自定义推送标识（如使用业务侧用户 ID），可在 registerPush 前调用 setRegistrationID。
注意：
混用场景下，自定义 registrationID 必须与 IM 登录使用的 userID 完全一致，否则会产生账号互踢导致推送丢失。
步骤4：测试推送链路
完成上述集成步骤后，需要通过发送测试消息验证链路是否打通。发送消息前请确认：
1. Android 13 及以上已允许通知权限；
2. Android 8.0 及以上目标通知渠道已开启（包括横幅、锁屏、声音开关）；
3. App 已置于后台。
发送测试消息可以采用下面几种方法：
控制台发送
REST API 发送
SDK API 发送
仅集成 TIMPush 的用户，建议优先使用腾讯云控制台接入测试能力验证离线推送。
操作路径：腾讯云控制台 > 推送服务 Push > 接入测试。在接入测试页面，可以指定 registrationID 或 userID 发送离线推送测试。
如果需要通过服务端发送推送，可参考 全员/标签推送。
如果您的项目已接入 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 初始化、登录和消息发送流程。
步骤5：处理通知点击跳转
通知点击跳转需要三步配合完成：控制台配置点击动作、发送推送时携带跳转参数、客户端注册监听并解析参数。三步缺一则跳转不生效。
配置控制台点击动作
在腾讯云控制台配置打开应用内指定页面。操作路径：腾讯云控制台 > 推送服务 Push > 基础配置 > 对应厂商证书 > 编辑 > 点击后续动作，选择打开应用内指定界面。
﻿
发送推送时携带 ext
发送离线推送时，通过 ext 字段携带跳转所需的业务信息（如目标页面、会话 ID 等）。ext 是一个字符串，结构由业务自定义，推荐使用 JSON 格式便于客户端解析。下文示例统一使用如下结构演示：
# conversationType 为 1 表示单聊（conversationID 填消息发送方 userID），为 2 表示群聊（conversationID 填 groupID）。
{"conversationID":"user_A","conversationType":1}
REST API 发送
SDK API 发送
通过 REST API 发送推送时，在请求体的 Ext 字段中设置 JSON 字符串：
{
    "MsgBody": [],
    "OfflinePushInfo": {
        "PushFlag": 0,
        "Title": "离线推送标题",
        "Desc": "离线推送内容",
        "Ext": "{\\"conversationID\\":\\"user_A\\",\\"conversationType\\":1}"
    }
}
控制台接入测试页面同样支持设置 Ext 字段，填入 JSON 字符串即可。
通过 V2TIMOfflinePushInfo 的 ext 属性携带跳转参数，再随消息一起发送。setExt 接收 byte[] 入参，业务自定义的 JSON 字符串需要先转成字节数组。
如果您接入了 TUIKit，TUIKit 内置的消息发送链路会自动用 OfflinePushExtInfo 组装 ext，无需手动设置。下方示例适用于自行调用 IM SDK 发送消息的场景。
Java
Kotlin
import android.util.Log;
﻿
import com.tencent.imsdk.v2.V2TIMManager;
import com.tencent.imsdk.v2.V2TIMMessage;
import com.tencent.imsdk.v2.V2TIMOfflinePushInfo;
import com.tencent.imsdk.v2.V2TIMSendCallback;
﻿
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setTitle("推送标题");
pushInfo.setDesc("推送内容");
// TODO: ext 由业务自定义，按需替换为您的目标页面、会话 ID 等参数。
String ext = "{\\"conversationID\\":\\"user_A\\",\\"conversationType\\":1}";
pushInfo.setExt(ext.getBytes());
﻿
V2TIMMessage message = V2TIMManager.getMessageManager().createTextMessage("Hello TIMPush");
V2TIMManager.getMessageManager().sendMessage(
        message,
        "<TARGET_USER_ID>", // 单聊填对端 userID，群聊该参数填 null
        null,               // 群聊填 groupID，单聊该参数填 null
        V2TIMMessage.V2TIM_PRIORITY_DEFAULT,
        false,
        pushInfo,
        new V2TIMSendCallback<V2TIMMessage>() {
            @Override
            public void onProgress(int progress) {}
﻿
            @Override
            public void onSuccess(V2TIMMessage msg) {
                Log.d("TIMPush", ">>>>> sendMessage success, msgID = " + msg.getMsgID());
            }
﻿
            @Override
            public void onError(int code, String desc) {
                Log.e("TIMPush", ">>>>> sendMessage failed, code = " + code + ", desc = " + desc);
            }
        });
import android.util.Log
import com.tencent.imsdk.v2.V2TIMManager
import com.tencent.imsdk.v2.V2TIMMessage
import com.tencent.imsdk.v2.V2TIMOfflinePushInfo
import com.tencent.imsdk.v2.V2TIMSendCallback
﻿
val pushInfo = V2TIMOfflinePushInfo()
pushInfo.title = "推送标题"
pushInfo.desc = "推送内容"
// TODO: ext 由业务自定义，按需替换为您的目标页面、会话 ID 等参数。
pushInfo.ext = "{\\"conversationID\\":\\"user_A\\",\\"conversationType\\":1}".toByteArray()
﻿
val message = V2TIMManager.getMessageManager().createTextMessage("Hello TIMPush")
V2TIMManager.getMessageManager().sendMessage(
    message,
    "<TARGET_USER_ID>", // 单聊填对端 userID，群聊该参数填 null
    null,               // 群聊填 groupID，单聊该参数填 null
    V2TIMMessage.V2TIM_PRIORITY_DEFAULT,
    false,
    pushInfo,
    object : V2TIMSendCallback<V2TIMMessage> {
        override fun onProgress(progress: Int) {}
﻿
        override fun onSuccess(msg: V2TIMMessage) {
            Log.d("TIMPush", ">>>>> sendMessage success, msgID = ${msg.msgID}")
        }
﻿
        override fun onError(code: Int, desc: String?) {
            Log.e("TIMPush", ">>>>> sendMessage failed, code = $code, desc = $desc")
        }
    }
)
客户端注册监听并解析 ext
请在 Application.onCreate() 中调用 addPushListener 注册 TIMPushListener，并在 onNotificationClicked 中解析 ext 后跳转到业务页面。
以下示例只演示解析 ext 的核心逻辑，跳转部分用 TODO 占位，请按自身业务补充。如果您接入了 TUIKit 并使用 OfflinePushExtInfo 组装的 ext，可改为 new Gson().fromJson(ext, OfflinePushExtInfo.class) 解析后再跳转。
Java
Kotlin
import android.app.Application;
import android.text.TextUtils;
import android.util.Log;
﻿
import com.tencent.timpush.TIMPushListener;
import com.tencent.timpush.TIMPushManager;
﻿
import org.json.JSONObject;
﻿
public class App extends Application {
    private static final String TAG = "TIMPush";
﻿
    @Override
    public void onCreate() {
        super.onCreate();
﻿
        TIMPushManager.getInstance().addPushListener(new TIMPushListener() {
            @Override
            public void onNotificationClicked(String ext) {
                Log.d(TAG, ">>>>> TIMPush notification clicked, ext = " + ext);
﻿
                if (TextUtils.isEmpty(ext)) {
                    return;
                }
﻿
                // 1. 解析 ext。JSON 结构由业务自定义，需与发送端约定一致。
                String conversationID;
                int conversationType;
                try {
                    JSONObject json = new JSONObject(ext);
                    conversationID = json.optString("conversationID");
                    conversationType = json.optInt("conversationType");
                } catch (Exception e) {
                    Log.e(TAG, ">>>>> parse ext failed: " + e.getMessage());
                    return;
                }
﻿
                // 2. TODO: 根据业务字段跳转到目标页面。
                //    若使用了 Chat / TUIKit，建议在用户登录成功后再跳转；
                //    冷启动场景可先把参数缓存起来，登录回调中再跳转。
            }
        });
    }
}
import android.app.Application
import android.text.TextUtils
import android.util.Log
﻿
import com.tencent.timpush.TIMPushListener
import com.tencent.timpush.TIMPushManager
﻿
import org.json.JSONObject
﻿
class App : Application() {
    override fun onCreate() {
        super.onCreate()
﻿
        TIMPushManager.getInstance().addPushListener(object : TIMPushListener() {
            override fun onNotificationClicked(ext: String?) {
                Log.d("TIMPush", ">>>>> TIMPush notification clicked, ext = $ext")
﻿
                if (TextUtils.isEmpty(ext)) return
﻿
                // 1. 解析 ext。JSON 结构由业务自定义，需与发送端约定一致。
                val conversationID: String
                val conversationType: Int
                try {
                    val json = JSONObject(ext)
                    conversationID = json.optString("conversationID")
                    conversationType = json.optInt("conversationType")
                } catch (e: Exception) {
                    Log.e("TIMPush", ">>>>> parse ext failed: ${e.message}")
                    return
                }
﻿
                // 2. TODO: 根据业务字段跳转到目标页面。
                //    若使用了 Chat / TUIKit，建议在用户登录成功后再跳转；
                //    冷启动场景可先把参数缓存起来，登录回调中再跳转。
            }
        })
    }
}
验证：点击通知后 onNotificationClicked 被调用，且 ext 内容与发送时设置的一致。
说明：
旧版本工程中可能仍使用 TUICore.registerEvent 回调或 LocalBroadcastManager 广播处理点击通知。这两种方式在当前版本仍可工作，但新接入用户建议优先使用 addPushListener。如需从旧方案迁移，删除旧的事件注册或广播注册代码，改为在 Application.onCreate() 中调用 addPushListener 即可，回调中获取到的 ext 内容与旧方案一致。
接入排查
如果接入完成收不到推送，请使用 排查工具 查看具体原因。排查后依然异常，请 联系我们 提交反馈。
资源	获取位置	用途
`SDKAppID`	腾讯云控制台 > 推送服务 Push > 概览	调用 `registerPush` 注册推送服务。
客户端密钥	腾讯云控制台 > 推送服务 Push > 概览 > 客户端密钥	调用 `registerPush` 注册推送服务。Push 的客户端密钥和 Chat 的客户端密钥不同，请勿混用。
`timpush-configs.json`	腾讯云控制台下载	放入 Android 应用模块的 `assets` 目录，TIMPush 注册时会读取该配置文件。
Android 工程包名	Android 工程 `applicationId`	需要与厂商平台应用包名保持一致。
目标厂商配置	对应厂商配置文档	确认厂商侧已开通推送服务，并已在腾讯云控制台添加厂商证书。
厂商配置文件	厂商开放平台	华为、荣耀、Google FCM 需要将对应 JSON 配置文件添加到工程中。
测试真机	目标厂商设备	厂商通道建议使用对应厂商真机验证。设备厂商与配置厂商不一致时，验证结果可能误导。
TIMPush 版本号 `VERSION`	更新日志	Gradle 依赖版本。本文使用 `VERSION` 占位，请替换为实际版本号。建议使用最新版本；如使用 7.7.5283 以下版本，荣耀通道配置可能有差异。
文件	DSL 类型
`settings.gradle`、`build.gradle`	Groovy DSL
`settings.gradle.kts`、`build.gradle.kts`	Kotlin DSL
场景	调用顺序	服务端可用于发送推送的目标标识	说明
仅使用 TIMPush	App 每次冷启动后调用 `registerPush（appKey = Push Key）`	`registrationID`	适用于营销 / 活动 / 通知推送，不接入 IM SDK。
IM SDK + TIMPush 先注册 Push 再登录	`registerPush(appKey = Push Key)` → IM `login`	登录前：`registrationID`；登录后：`registrationID` + `userID`	适用于希望用户未登录时也能收到营销推送的场景。
IM SDK + TIMPush 先登录再注册 Push	IM `login` → `registerPush(appKey = null)`	登录后：`userID` 注册后：`userID` + `registrationID`，此时 `registrationID` = `userID`	适用于希望用户登录后能收到 Chat 离线消息和营销推送的场景。
Android

本页目录：

前提条件

AI 集成

手动集成

步骤1：集成 TIMPush SDK

下载并添加 TIMPush 配置文件

配置 Gradle 仓库

集成 TIMPush 基础依赖

设置混淆规则

步骤2：集成厂商通道 SDK

前置

1. 集成 TIMPush 厂商依赖

2. 配置消息触达统计（可选）

3. 配置消息分类（可选）

前置

1. 添加厂商配置文件

2. 配置 Gradle 插件

追加厂商 Maven 仓库

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

4. 配置消息触达统计（可选）

5. 配置消息分类（可选）

前置

1. 集成 TIMPush 厂商依赖

2. 配置消息触达统计（可选）

3. 配置消息分类（可选）

OPPO 新规则配置

OPPO 旧规则配置

前置

1. 集成 TIMPush 厂商依赖

2. 配置 manifestPlaceholders 和 AndroidManifest.xml

3. 配置消息触达统计（可选）

4. 配置消息分类（可选）

前置

1. 添加厂商配置文件

2. 配置 Gradle 插件

追加厂商 Maven 仓库

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

4. 配置 manifestPlaceholders 和 AndroidManifest.xml

5. 配置消息触达统计（可选）

6. 配置消息分类（可选）

前置

1. 集成 TIMPush 厂商依赖

2. 配置消息触达统计（可选）

3. 配置消息分类（可选）

前置

1. 添加厂商配置文件

2. 配置 Gradle 插件

配置项目级插件依赖

在应用模块启用插件

3. 集成 TIMPush 厂商依赖

4. 配置消息触达统计（可选）

5. 配置消息分类（可选）

步骤3：注册推送服务

调用 registerPush

自定义 registrationID（可选）

步骤4：测试推送链路

步骤5：处理通知点击跳转

配置控制台点击动作

发送推送时携带 ext

客户端注册监听并解析 ext

接入排查

发送推送时携带 `ext`

客户端注册监听并解析 `ext`
