tencent cloud

概述

即时通信 IM 的终端用户需要随时都能够得知最新的消息，而由于移动端设备的性能与电量有限，当 App 处于后台时，为了避免维持长连接而导致的过多资源消耗，即时通信 IM 推荐您使用各厂商提供的系统级推送通道来进行消息通知，系统级的推送通道相比第三方推送拥有更稳定的系统级长连接，可以做到随时接受推送消息，且资源消耗大幅降低。

注意：

• 在没有主动退出登录的情况下，应用退后台、手机锁屏、或者应用进程被用户主动杀掉三种场景下，如果想继续接收到 IM 消息提醒，可以接入即时通信 IM 离线推送。
• 如果应用主动调用 logout 退出登录，或者多端登录被踢下线，即使接入了 IM 离线推送，也收不到离线推送消息。

集成 TUIOfflinePush 跑通离线推送功能

集成 TUIOfflinePush 组件之前，请您先 注册应用到厂商推送平台，登录腾讯云账号进行 IM 控制台配置 和 配置离线推送跳转界面。之后按照如下步骤操作即可快速接入 IM 离线推送。

注意：

• 如果您想尽可能简单地接入 TUIOfflinePush 组件，您需要使用 TUICore 组件中的 TUILogin 提供的 login/logout 接口登录/登出，此时 TUIOfflinePush 组件会自动感知登录/登出事件。如果您不想使用 TUILogin 提供的接口，您需要在完成登录/登出操作后，手动调用 TUIOfflinePushManager 的接口 registerPush/unRegisterPush。
• 组件支持的厂商有：小米、华为、荣耀、OPPO、vivo、魅族和 Google FCM。

步骤1：集成 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. 下载配置文件添加到工程根目录。

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'

步骤2：推送参数配置

推送证书添加成功之后，IM 控制台会为您分配一个证书 ID，请您填充到 PrivateConstants 的配置参数里，该证书 ID 会在注册推送服务和上报 token 时使用, 以小米为例：

填充的参数如下：

 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 ******/
 }

以上步骤完成后，就可以收到离线推送通知了。

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

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

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

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

常见问题

离线推送怎么自定义推送的声音？

从 SDK 6.1.2155 版本开始，支持设置自定义铃音，支持机型有华为、小米、FCM 和 APNS。方法参见：V2TIMOfflinePushInfo 接口 setAndroidSound() 和 setIOSSound()。

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

1. OPPO 手机

OPPO 手机收不到推送一般有以下几种情况：

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

2. Google FCM

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

3. 发送消息为自定义消息

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

4. 设备通知栏设置影响

离线推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：

• “手机设置-通知-锁屏通知-隐藏或者不显示通知”，会影响锁屏状态下离线推送通知显示。
• “手机设置-通知-更多通知设置-状态栏显示通知图标”，会影响状态栏下离线推送通知的图标显示。
• “手机设置-通知-应用的通知管理-允许通知”，打开关闭会直接影响离线推送通知显示。
• “手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”，会影响离线推送通知铃音的效果。

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

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

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

单击离线推送消息的通知栏，跳转到指定界面，原理是后台根据您在控制台配置的各个厂商的跳转方式和界面参数，根据厂商接口规则，传递给厂商服务器，单击时候进行对应界面启动跳转。对应界面启动还依赖清单文件的配置，必须和控制台配置的相对应，才能正确启动和跳转。

1. 首先需要重点排查下控制台和清单文件相关配置是否对应且正确，可参见 TUIKitDemo 的配置，注意部分厂商提供接口方式存在差异。
2. 如果跳转到了配置的界面，需要再看下配置界面内离线消息的解析和界面重定向是否正常。

厂商推送限制

1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，离线推送消息会受厂商推送消息分类影响，与预期会有差异。
2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。
   如果离线推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
   • 华为：将推送消息分为服务与通讯类和资讯营销类，推送效果和策略不同。另外，消息分类还和自分类权益有关：
     • 无自分类权益，推送消息厂商还会进行二次智能分类 。
     • 有申请自分类权益，消息分类会按照自定义的分类进行推送。
       具体请参见 厂商描述。
   • vivo：将推送消息分为系统消息类和运营消息类，推送效果和策略不同。系统消息类型还会进行厂商的智能分类二次修正，若智能分类识别出不是系统消息，会自动修正为运营消息，如果误判可邮件申请反馈。另外，消息推送也受日推总数量限制，日推送量由应用在厂商订阅数统计决定。
     具体请参见 厂商描述1 或 厂商描述2。
   • OPPO：将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。
     具体请参见 厂商描述1 或 厂商描述2。
   • 小米：将推送消息分为重要消息类和普通消息类，推送效果和策略不同。其中重要消息类型仅允许即时通讯消息、个人关注动态提醒、个人事项提醒、个人订单状态变化、个人财务提醒、个人状态变化、个人资源变化、个人设备提醒这8类消息推送，可以在厂商控制台申请开通。普通消息类型推送数量有限制。
     具体请参见 厂商描述1 或 厂商描述2。
   • 魅族：推送消息数量有限制。
     具体请参见 厂商描述。
   • FCM：推送上行消息频率有限制。
     具体请参见 厂商描述。