Android

Download
聚焦模式
字号
最后更新时间： 2026-08-13 10:13:10
Chat 注意：
自集成推送仅支持普通消息推送，已停止维护。强烈建议您使用 推送插件 (TIMPush)，只需进行简单配置，即可一键式集成接入多个厂商的推送服务，不仅支持普通消息推送，还支持全员推送和按用户标签推送，具备完整的推送生命周期查询、数据统计、问题排查等功能，为您提供稳定、及时、多样化的一站式综合推送服务。
本文旨在介绍如何自主集成各家厂商推送服务。
跑通离线推送功能
步骤1：注册应用到厂商推送平台
离线推送功能依赖厂商原始通道，您需要将自己的应用注册到各个厂商的推送平台，得到 AppID 和 AppKey 等参数。目前国内支持的手机厂商有：小米、华为、荣耀、OPPO、VIVO、魅族，境外支持 Google FCM。
步骤2：Chat 控制台配置
登录腾讯云 即时通信 Chat 控制台 ，添加各个厂商推送证书，并将您在步骤1中获取的各厂商的 AppId、AppKey、AppSecret 等参数配置给 Chat 控制台的推送证书，其中单击后续动作参见步骤3。
打开应用内指定界面：单击通知栏会根据配置自定义跳转界面，详见 自定义点击跳转。
小米
华为
OPPO
vivo
魅族
荣耀
Google FCM
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
说明：
Client ID 对应 AppID，Client Secret 对应 AppSecret。
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
厂商推送平台
Chat 控制台配置
﻿
﻿
﻿
﻿
﻿
﻿
注意：
对于小米厂商，如果在厂商开发者官网配置了 ChannelID，需要在 即时通信 Chat 控制台 配置同样的 ChannelID，否则可能推送不成功。
步骤3：配置离线推送跳转界面
收到离线推送后，通知栏会显示推送信息如图所示，单击通知栏会打开应用并进入配置的跳转界面。请您根据各个厂商的点击跳转配置文档，配置单击通知消息后跳转的 Activity。
步骤4：配置厂商推送规则
应用离线参数配置
﻿步骤2 推送证书添加成功之后，Chat 控制台会为您分配一个对应厂商的证书 ID，请您进行本地保存。在登录完成后注册推送服务时候，将获取的厂商 token 和该证书 ID 通过接口 setOfflinePushConfig 给到后台。以小米为例：
推送证书 ID 如下：
﻿
本地保存证书 ID 和推送参数：
public class PrivateConstants {
/****** 小米离线推送参数start ******/
// 在腾讯云控制台上传第三方推送证书后分配的证书 ID
public static final long XM_PUSH_BUZID = 您应用分配的证书 ID;
// 小米开放平台分配的应用APPID及APPKEY
public static final String XM_PUSH_APPID = "您应用分配的 APPID";
public static final String XM_PUSH_APPKEY = "您应用分配的 APPKEY";
/****** 小米离线推送参数end ******/
}
清单文件配置厂商推送权限相关
    清单文件中需要添加各个厂商的推送规则以及推送继承类，请参考具体厂商文档接入和添加。
vivo 和荣耀适配
根据 vivo 和荣耀厂商接入指引，需要将 APPID 和 APPKEY 添加到清单文件中，否则会出现编译问题：
方法1
方法2
android {
    ...
    defaultConfig {
            ...
        manifestPlaceholders = [
                "VIVO_APPKEY" : "您应用分配的证书 APPKEY",
                "VIVO_APPID" : "您应用分配的证书 APPID"
                "HONOR_APPID" : "您应用分配的证书 APPID"
        ]
    }
}
// vivo begin
<receiver android:name="com.tencent.qcloud.tim.demo.thirdpush.VIVOPushMessageReceiverImpl">
    <intent-filter>
        <!-- 接收push消息 -->
        <action android:name="com.vivo.pushclient.action.RECEIVE" />
    </intent-filter>
</receiver>
﻿
<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
﻿
// honor begin
<service
    android:name="com.tencent.qcloud.tim.tuiofflinepush.oempush.MyHonorMessageService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.hihonor.push.action.MESSAGING_EVENT" />
    </intent-filter>
 </service>
﻿
<meta-data tools:replace="android:value"
    android:name="com.hihonor.push.app_id"
    android:value="您应用分配的证书 APPID" />
// honor end
华为和 Google FCM 适配
华为和 Google FCM 需要按照厂商方法，集成对应的 plugin 和 json 配置文件。
1.1 下载配置文件添加到工程根目录。
华为
Google FCM
﻿
﻿
﻿
﻿
﻿
﻿
1.2 在项目级 build.gradle 文件中 buildscript -> dependencies 下添加以下配置：
classpath 'com.google.gms:google-services:4.2.0'
classpath 'com.huawei.agconnect:agcp:1.4.1.300'
在项目级 build.gradle 文件中 allprojects -> repositories 下添加以下配置：
mavenCentral()
// 配置HMS Core SDK的Maven仓地址。
maven {url 'https://developer.huawei.com/repo/'}
添加后效果如下：
repositories {
...
 // 配置HMS Core SDK的Maven仓地址。
 maven {url 'https://developer.huawei.com/repo/'}
}
﻿
dependencies {
...
classpath 'com.google.gms:google-services:4.2.0'
classpath 'com.huawei.agconnect:agcp:1.4.1.300'
}
1.3 在应用级 build.gradle 文件中添加下方配置。
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.huawei.agconnect'
1.4 单击项目右上角 Sync Now 同步项目。
步骤5：集成厂商推送 SDK
集成 SDK
在应用的 build.gradle 文件中添加厂商推送 SDK。
dependencies {
 ......
 // 华为
 implementation 'com.tencent.timpush:huawei:7.7.5282'
 // Google FCM
 implementation 'com.tencent.timpush:fcm:7.7.5282'
 // 小米
 implementation 'com.tencent.timpush:xiaomi:7.7.5282'
 // OPPO
 implementation 'com.tencent.timpush:oppo:7.7.5282'
 // vivo
 implementation 'com.tencent.timpush:vivo:7.7.5282'
 // honor
 implementation 'com.tencent.timpush:honor:7.7.5282'
 // 魅族
 implementation 'com.tencent.timpush:meizu:7.7.5282'
}
添加推送类
    引入集成厂商推送类，各个厂商推送方式有区别，具体详见厂商的接入文档。
推送证书和 token 上报后台
调用 setOfflinePushConfig 接口上报推送 token。构造 V2TIMOfflinePushConfig 类，需设置 businessID 为对应厂商的证书 ID，上报注册厂商推送服务获取的 token。
V2TIMOfflinePushConfig v2TIMOfflinePushConfig = null;
// 需要设置 businessID 为对应厂商的证书 ID，上报注册厂商推送服务获取的 token。  
v2TIMOfflinePushConfig = new V2TIMOfflinePushConfig(businessID, token);
V2TIMManager.getOfflinePushManager().setOfflinePushConfig(v2TIMOfflinePushConfig, new V2TIMCallback() {
      @Override
      public void onError(int code, String desc) {
          DemoLog.d(TAG, "setOfflinePushToken err code = " + code);
      }
﻿
      @Override
      public void onSuccess() {
          DemoLog.d(TAG, "setOfflinePushToken success");
      }
});
步骤6：前后台状态同步
 如果您的应用退到后台，收到新消息时需要在手机通知栏进行展示，请您调用 ChatSDK 的 doBackground() 接口，将应用的状态同步给 Chat 后台；当应用回到前台时，请您调用 ChatSDK 的 doForeground() 接口，将应用的状态同步给 Chat 后台。
// 应用切到后台时
V2TIMManager.getOfflinePushManager().doBackground(totalCount, new V2TIMCallback() {
    @Override
    public void onError(int code, String desc) {
        DemoLog.e(TAG, "doBackground err = " + code + ", desc = " + desc);
    }
﻿
    @Override
    public void onSuccess() {
        DemoLog.i(TAG, "doBackground success");
    }
});
// 应用切回前台时
V2TIMManager.getOfflinePushManager().doForeground(new V2TIMCallback() {
    @Override
    public void onError(int code, String desc) {
        DemoLog.e(TAG, "doForeground err = " + code + ", desc = " + desc);
    }
﻿
    @Override
    public void onSuccess() {
        DemoLog.i(TAG, "doForeground success");
    }
});
步骤7：发消息时设置离线推送参数
调用 sendMessage 发送消息时，您可以通过 V2TIMOfflinePushInfo 设置离线推送参数，可以参照 ChatProvider 的 sendMessage() 方法：
OfflineMessageContainerBean containerBean = new OfflineMessageContainerBean();
OfflineMessageBean entity = new OfflineMessageBean();
entity.content = message.getExtra().toString();
entity.sender = message.getFromUser();
entity.nickname = chatInfo.getChatName();
entity.faceUrl = TUIChatConfigs.getConfigs().getGeneralConfig().getUserFaceUrl();
containerBean.entity = entity;
﻿
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setExt(new Gson().toJson(containerBean).getBytes());
// OPPO必须设置ChannelID才可以收到推送消息，这个channelID需要和控制台一致
v2TIMOfflinePushInfo.setAndroidOPPOChannelID("tuikit");
﻿
final V2TIMMessage v2TIMMessage = message.getTimMessage();
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
    V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
        @Override
        public void onProgress(int progress) {
﻿
        }
﻿
        @Override
        public void onError(int code, String desc) {
            TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
        }
﻿
        @Override
        public void onSuccess(V2TIMMessage v2TIMMessage) {
            TUIChatLog.v(TAG, "sendMessage onSuccess:" + v2TIMMessage.getMsgID());
            message.setMsgTime(v2TIMMessage.getTimestamp());
            TUIChatUtils.callbackOnSuccess(callBack, message);
        }
    });
步骤8：解析离线推送消息
收到离线推送的通知栏消息，点击会自动跳转到您在 步骤3 配置的跳转界面，可以在界面启动的 onResume() 方法中，调用 getIntent().getExtras() 获取透传的离线推送参数再自定义跳转。具体可以参照 TUIKitDemo 的 handleOfflinePush() 方法。
private void handleOfflinePush() {
    final OfflineMessageBean bean = OfflineMessageDispatcher.parseOfflineMessage(getIntent());
        if (bean != null) {
            setIntent(null);
            NotificationManager manager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            if (manager != null) {
                manager.cancelAll();
            }
﻿
            if (bean.action == OfflineMessageBean.REDIRECT_ACTION_CHAT) {
                if (TextUtils.isEmpty(bean.sender)) {
                    return;
                }
                TUIUtils.startChat(bean.sender, bean.nickname, bean.chatType);
            }
        }
}
﻿
以上完成后，当您的应用退到后台或者进程被杀掉时，消息会进行离线推送通知栏展示，可单击通知栏跳转到设定的应用界面，完成实现离线推送功能。
离线推送自定义推送铃音
Android 8.0 以前系统设置，接口调用 setAndroidSound() 和 setIOSSound()。
1. 定制的铃声资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。
2. 消息指定使用自定义的铃音。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidSound("铃音名称");
v2TIMOfflinePushInfo.setIOSSound("铃音名称.mp3");
﻿
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
 V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
@Override
 public void onProgress(int progress) {
     TUIChatUtils.callbackOnProgress(callBack, progress);
 }
﻿
@Override
 public void onError(int code, String desc) {
    TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
 }
﻿
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
﻿
 }
});
注意：
ChatSDK  6.1.2155  及以上版本支持。
接口支持华为、小米、FCM 和 APNS。
Android 8.0 及以后系统设置需要通过 channel 实现。
华为 与 APNS
华为、APNS 仍然调用 setAndroidSound() 和 setIOSSound() 来设置离线推送铃音提示。
小米
1.1 登录厂商控制台 创建 channel 并做好配置，其中铃音文件需要添加到您本地 Android Studio 工程的 raw 目录下。
﻿
﻿
﻿
1.2 发送消息指定自定义铃音的 channel ID，详见 setAndroidXiaoMiChannelID。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidXiaoMiChannelID("厂商申请的 channel ID");
﻿
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
 V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
@Override
 public void onProgress(int progress) {
    TUIChatUtils.callbackOnProgress(callBack, progress);
 }
﻿
@Override
 public void onError(int code, String desc) {
    TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
 }
﻿
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
﻿
 }
});
FCM
1.1 创建需要自定义铃音的 channel。
您需要在代码中先默认创建好带自定义铃声的 channel，铃音文件需要添加到您本地 Android Studio 工程的 raw 目录下，并记录下 channel ID 的名称。
1.2 发送消息指定自定义铃音的 channel ID，详见 setAndroidFCMChannelID。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidFCMChannelID(PrivateConstants.fcmPushChannelId);
﻿
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
 V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
@Override
 public void onProgress(int progress) {
  TUIChatUtils.callbackOnProgress(callBack, progress);
 }
﻿
@Override
 public void onError(int code, String desc) {
  TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
 }
﻿
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
﻿
 }
});
注意：
ChatSDK 7.0.3754 及以上版本支持。
FCM 自定义铃声或者设置 channelID 仅支持证书模式。
﻿
常见问题
收不到离线推送怎么排查？
OPPO 手机
OPPO 手机收不到推送一般有以下几种情况：
按照 OPPO 推送官网要求，在 Android 8.0 及以上系统版本的 OPPO 手机上必须配置 ChannelID，否则推送消息无法展示。配置方法可以参见 setAndroidOPPOChannelID。
OPPO 安装应用通知栏显示默认关闭，需要确认下开关状态。
Google FCM
收不到推送需要确认下 Chat 控制台是否正确上传证书。排查路径参照文档 “Chat 控制台配置 - Google FCM”，对照示意图看下是否添加正确。
发送消息为自定义消息
自定义消息的离线推送和普通消息不太一样，自定义消息的内容我们无法解析，不能确定推送的内容，所以默认不推送，如果您有推送需求，需要您在 sendMessage 的时候设置 offlinePushInfo 的 desc 字段，推送的时候会默认展示 desc 信息。
设备通知栏设置影响
离线推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
“手机设置-通知-锁屏通知-隐藏或者不显示通知”，会影响锁屏状态下离线推送通知显示。
“手机设置-通知-更多通知设置-状态栏显示通知图标”，会影响状态栏下离线推送通知的图标显示。
“手机设置-通知-应用的通知管理-允许通知”，打开关闭会直接影响离线推送通知显示。
“手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”，会影响离线推送通知铃音的效果。
按照流程接入完成，还是收不到离线推送
首先在 Chat 控制台通过 离线测试工具 自测下是否可以正常推送。
推送异常情况，设备状态异常，需要检查下 Chat 控制台配置各项参数是否正确，再者需要检查下代码初始化注册逻辑，包括厂商推送服务注册和 Chat 设置离线推送配置相关逻辑是否正确设置。
推送异常情况，设备状态正常，需要看下是否需要正确填写 channel ID 或者后台服务是否正常。
离线推送依赖厂商能力，一些简单的字符可能会被厂商过滤不能透传推送。
如果离线推送消息出现推送不及时或者偶尔收不到情况，需要看下厂商的推送限制。
跳转界面不成功怎么排查？
单击离线推送消息的通知栏，跳转到指定界面，原理是后台根据您在控制台配置的各个厂商的跳转方式和界面参数，根据厂商接口规则，传递给厂商服务器，单击时候进行对应界面启动跳转。对应界面启动还依赖清单文件的配置，必须和控制台配置的相对应，才能正确启动和跳转。
1. 首先需要重点排查下控制台和清单文件相关配置是否对应且正确，可参见 TUIKitDemo 的配置，注意部分厂商提供接口方式存在差异。
2. 如果跳转到了配置的界面，需要再看下配置界面内离线消息的解析和界面重定向是否正常。
厂商推送限制
1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，离线推送消息会受厂商推送消息分类影响，与预期会有差异。
2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。
3. 如果离线推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
华为：华为推送从 EMUI 10.0版本开始将通知消息智能分成两个级别：服务与通讯和资讯营销。EMUI 10.0之前的版本没有对通知消息进行分类，只有一个级别，消息全部通过“默认通知”渠道展示，等价于 EMUI 10.0的服务与通讯。资讯营销类消息的每日推送数量自2023年01月05日起根据应用类型对推送数量进行上限管理，服务与通讯类消息每日推送数量不受限。另外，消息分类还和自分类权益有关：
无自分类权益，推送消息厂商还会进行二次智能分类 。
有申请自分类权益，且推送消息携带 category 字段，消息会按照自定义的分类进行推送，详见 setAndroidHuaWeiCategory。
具体请参见 厂商描述1 或 厂商描述2。
荣耀：荣耀手机推送和系统版本有关。
当前荣耀通道仅支持国内 Magic UI 4.0 及以上和海外 Magic UI 4.2 及以上荣耀设备使用。
低于上述版本的荣耀设备可以按照华为厂商接入推送。
具体请参见 厂商描述。
vivo：推送服务将于 2023 年 4 月 3 日起，优化消息分类规则，并调整不同消息类别的数量限制。
关于消息分类优化，增加二级分类 category 字段，并根据不同二级分类配置不同推送速度。接口详见 setAndroidVIVOCategory 。category 默认值可前往 Chat 控制台配置。
关于消息数量限制调整，系统消息可申请不限量权限，不限制单应用单用户单日接收数量；运营消息单日可推送量级 = 通知开启的有效用户数 * 倍数，默认倍数为 2 倍，新闻资讯类应用为 3 倍。单应用单用户单日接收数量限制为 2 条，新闻资讯类应用为 5 条。
具体请参见 厂商描述1 或 厂商描述2。
OPPO：将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。
具体请参见 厂商描述1 或 厂商描述2。
小米：将推送消息分为“私信消息”和“公信消息”两个类别，默认通道为公信消息。公信消息的单日推送数量将进行上限管理，公信消息适用于推送热点新闻、新品推广、平台公告、社区话题、有奖活动等，多为用户普适性的内容。私信消息适用于推送聊天消息、个人订单变化、快递通知、交易提醒、IOT系统通知等与私人通知相关的内容，通知消息的推送数量不受限制。消息分类管理实现需要在厂商控制台进行 channel 申请及接入。
具体请参见 厂商描述1 或 厂商描述2。
魅族：推送消息数量有限制。
具体请参见 厂商描述。
FCM：推送上行消息频率有限制。
具体请参见 厂商描述。
﻿