即时通信 IM
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 即时通信 IM

Android

最近更新时间：2023-11-20 11:54:41

我的收藏

本页目录：

概述

即时通信 IM 的终端用户需要随时都能够得知最新的消息，而由于移动端设备的性能与电量有限，当 App 处于后台时，为了避免维持长连接而导致的过多资源消耗，即时通信 IM 推荐您使用各厂商提供的系统级推送通道来进行消息通知，系统级的推送通道相比第三方推送拥有更稳定的系统级长连接，可以做到随时接受推送消息，且资源消耗大幅降低。
注意
在没有主动退出登录的情况下，应用退后台、手机锁屏、或者应用进程被用户主动杀掉三种场景下，如果想继续接收到 IM 消息提醒，可以接入即时通信 IM 离线推送。
如果应用主动调用 logout 退出登录，或者多端登录被踢下线，即使接入了 IM 离线推送，也收不到离线推送消息。

集成 TUIOfflinePush 跑通离线推送功能

集成 TUIOfflinePush 组件之前，请您先 注册应用到厂商推送平台，登录腾讯云账号进行 IM 控制台配置，其中离线推送跳转界面配置请关注 步骤1。之后按照如下步骤操作即可快速接入 IM 离线推送。
注意
如果您想尽可能简单地接入 TUIOfflinePush 组件，您需要使用 TUICore 组件中的 TUILogin 提供的 login/logout 接口登录/登出，此时 TUIOfflinePush 组件会自动感知登录/登出事件。如果您不想使用 TUILogin 提供的接口，您需要在完成登录/登出操作后，手动调用 TUIOfflinePushManager 的接口 registerPush/unRegisterPush。
组件支持的厂商有：小米、华为、荣耀、OPPO、vivo、魅族和 Google FCM。

步骤1：配置离线推送跳转界面

各个厂商的跳转界面配置方式有所不同，具体如下：
厂商
单击后续动作
应用内指定界面
小米
打开应用内指定页面
intent://com.tencent.qcloud.uniapp/detail#Intent;scheme=pushscheme;launchFlags=0x4000000;end
华为
荣耀
vivo
OPPO
activity：com.tencent.qcloud.tim.tuiofflinepush.OpenActivity
魅族
com.tencent.qcloud.tim.tuiofflinepush.OpenActivity
Google FCM
不需要配置
默认会跳转至应用的 Launcher 界面
当收到推送时候，单击通知栏的单击事件，组件会以回调或者广播形式通知应用，应用在回调中配置 App 的跳转页面即可。
回调方式如下：
TUICore.registerEvent(TUIConstants.TUIOfflinePush.EVENT_NOTIFY,
    TUIConstants.TUIOfflinePush.EVENT_NOTIFY_NOTIFICATION, new ITUINotification() {
        @Override
        public void onNotifyEvent(String key, String subKey, Map<String, Object> param) {
            Log.d(TAG, "onNotifyEvent key = " + key + "subKey = " + subKey);
            if (TUIConstants.TUIOfflinePush.EVENT_NOTIFY.equals(key)) {
                if (TUIConstants.TUIOfflinePush.EVENT_NOTIFY_NOTIFICATION.equals(subKey)) {
                    if (param != null) {
                        String extString = (String)param.get(TUIConstants.TUIOfflinePush.NOTIFICATION_EXT_KEY);
                        TUIUtils.handleOfflinePush(extString, null);
                    }
                }
            }
        }
    });
广播方式如下：
// 动态注册广播
IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction(TUIConstants.TUIOfflinePush.NOTIFICATION_BROADCAST_ACTION);
LocalBroadcastManager.getInstance(context).registerReceiver(localReceiver, intentFilter);

//广播接收者
public class OfflinePushLocalReceiver extends BroadcastReceiver {
    public static final String TAG = OfflinePushLocalReceiver.class.getSimpleName();

    @Override
    public void onReceive(Context context, Intent intent) {
        DemoLog.d(TAG, "BROADCAST_PUSH_RECEIVER intent = " + intent);
        if (intent != null) {
            String ext = intent.getStringExtra(TUIConstants.TUIOfflinePush.NOTIFICATION_EXT_KEY);
            TUIUtils.handleOfflinePush(ext, null);
        } else {
            DemoLog.e(TAG, "onReceive ext is null");
        }
    }
}
注意
使用推送组件回调跳转需要使用 6.6.3002 及以上版本。

步骤2：集成 TUIOfflinePush 组件

api project(':tuiofflinepush')
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. 下载配置文件添加到工程根目录。
华为
Google FCM






2. 在项目级 build.gradle 文件中 buildscript -> dependencies 下添加以下配置：
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'
}
3. 在应用级 build.gradle 文件中添加下方配置。
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.huawei.agconnect'

步骤3：推送参数配置

推送证书添加成功之后，IM 控制台会为您分配一个证书 ID，请您填充到 PrivateConstants 的配置参数里，该证书 ID 会在注册推送服务和上报 token 时使用, 以小米为例：
推送证书 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 ******/
   }
以上步骤完成后，就可以收到离线推送通知了。

步骤4：发消息时设置离线推送参数

发送消息时，请您设置离线推送参数，具体请参见 发消息时设置离线推送参数。

步骤5：解析离线推送消息

收到离线推送的通知栏消息，单击会自动跳转到您配置的跳转界面，该界面可以获取透传的离线消息，请您参见 解析离线推送消息。

离线推送自定义推送铃音

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) {

 }
});
注意
IMSDK 6.1.2155 及以上版本支持。
接口支持华为、小米、FCM 和 APNS。

Android 8.0 及以后系统设置需要通过 channel 实现

华为 和 ANPS

华为、APNS 仍然调用 setAndroidSound() 和 setIOSSound() 来设置离线推送铃音提示。

小米

1. 登录厂商控制台 创建 channel 并做好配置，其中铃音文件需要添加到您本地 Android Studio 工程的 raw 目录下。



2. 发送消息指定自定义铃音的 channel ID，详情请参见 setAndroidXiaoMiChannelID。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidXiaoMiChannelID("厂商申请的 channel ID");
<Dx-empty />
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);
 }
<Dx-empty />
@Override
 public void onError(int code, String desc) {
  TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
 }
<Dx-empty />
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
<Dx-empty />
 }
});


FCM

1. 创建需要自定义铃音的 channel。
TUIOfflinePush 组件已经默认创建好带自定义铃音的 channel。铃音文件需要添加到您本地 Android Studio 工程的 raw 目录下，并指定铃音名称和 channel ID 的名称，详情请参见 PrivateConstants。
public class PrivateConstants {

...

// FCM 通道指定 channel ID
public static String fcmPushChannelId = "fcm_push_channel";
// FCM 上面指定通道的推送铃音名称，Android 工程里 raw 目录中的铃音文件名，不需要后缀名。
public static String fcmPushChannelSoundName = "private_ring";

...

}
打开组件自定义铃音开关，详情请参见 TUIOfflinePushConfig。
TUIOfflinePushConfig.getInstance().setAndroidPrivateRing(true);
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) {

 }
});
注意
IMSDK 7.0.3754 及以上版本支持。
FCM 自定义铃声或者设置 channel id 仅支持证书模式。




常见问题

收不到离线推送怎么排查？

OPPO 手机

OPPO 手机收不到推送一般有以下几种情况：
按照 OPPO 推送官网要求，在 Android 8.0 及以上系统版本的 OPPO 手机上必须配置 ChannelID，否则推送消息无法展示。配置方法可以参见 setAndroidOPPOChannelID。
OPPO 安装应用通知栏显示默认关闭，需要确认下开关状态。

Google FCM

收不到推送需要确认下 IM 控制台是否正确上传证书。排查路径请参见 IM 控制台配置 > Google FCM，对照示意图看下是否添加正确。

发送消息为自定义消息

自定义消息的离线推送和普通消息不太一样，自定义消息的内容我们无法解析，不能确定推送的内容，所以默认不推送，如果您有推送需求，需要您在 sendMessage 的时候设置 offlinePushInfo 的 desc 字段，推送的时候会默认展示 desc 信息。

设备通知栏设置影响

离线推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
“手机设置-通知-锁屏通知-隐藏或者不显示通知”，会影响锁屏状态下离线推送通知显示。
“手机设置-通知-更多通知设置-状态栏显示通知图标”，会影响状态栏下离线推送通知的图标显示。
“手机设置-通知-应用的通知管理-允许通知”，打开关闭会直接影响离线推送通知显示。
“手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”，会影响离线推送通知铃音的效果。

按照流程接入完成，还是收不到离线推送

首先在 IM 控制台通过 离线测试工具 自测下是否可以正常推送。 推送异常情况，设备状态异常，需要检查下 IM 控制台配置各项参数是否正确，再者需要检查下代码初始化注册逻辑，包括厂商推送服务注册和 IM 设置离线推送配置相关逻辑是否正确设置。 推送异常情况，设备状态正常，需要看下是否需要正确填写 channel ID 或者后台服务是否正常。
离线推送依赖厂商能力，一些简单的字符可能会被厂商过滤不能透传推送。
如果离线推送消息出现推送不及时或者偶尔收不到情况，需要看下厂商的推送限制。

跳转界面不成功怎么排查？

单击离线推送消息的通知栏，跳转到指定界面，原理是后台根据您在控制台配置的各个厂商的跳转方式和界面参数，根据厂商接口规则，传递给厂商服务器，单击时候进行对应界面启动跳转。对应界面启动还依赖清单文件的配置，必须和控制台配置的相对应，才能正确启动和跳转。
1. 首先需要重点排查下控制台和清单文件相关配置是否对应且正确，可参见 TUIKitDemo 的配置，注意部分厂商提供接口方式存在差异。
2. 如果跳转到了配置的界面，需要再看下配置界面内离线消息的解析和界面重定向是否正常。

厂商推送限制

1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，离线推送消息会受厂商推送消息分类影响，与预期会有差异。
2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。 如果离线推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
华为：华为推送从 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 。
关于消息数量限制调整，系统消息可申请不限量权限，不限制单应用单用户单日接收数量；运营消息单日可推送量级 = 通知开启的有效用户数 * 倍数，默认倍数为 2 倍，新闻资讯类应用为 3 倍。单应用单用户单日接收数量限制为 2 条，新闻资讯类应用为 5 条。 具体请参见 厂商描述1 或 厂商描述2。
OPPO：将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。 具体请参见 厂商描述1 或 厂商描述2。
小米：将推送消息分为“私信消息”和“公信消息”两个类别，默认通道为公信消息。公信消息的单日推送数量将进行上限管理，公信消息适用于推送热点新闻、新品推广、平台公告、社区话题、有奖活动等，多为用户普适性的内容。私信消息适用于推送聊天消息、个人订单变化、快递通知、交易提醒、IOT系统通知等与私人通知相关的内容，通知消息的推送数量不受限制。消息分类管理实现需要在厂商控制台进行 channel 申请及接入。 具体请参见 厂商描述1 或 厂商描述2。
魅族：推送消息数量有限制。 具体请参见 厂商描述。
FCM：推送上行消息频率有限制。 具体请参见 厂商描述。

中国站