跳到主要内容

开始集成推送(旧版)

融云 SDK 支持集成三方推送通道与融云自建推送通道(RongPush)。

注意

本文适用于 5.6.0 版本之前的 IMLib、IMKit 或其他依赖 IMLib 的融云客户端 SDK。从 5.6.0 版本开始,融云推出集成方式更简单的 Push 2.0 集成方案,欢迎使用。

推送服务能力

推送支持「离线消息推送」和「不落地通知」两种场景。

离线消息推送通知

假设用户仅在一台设备上登录,如果主动断开连接(disconnect())或者应用程序已被用户或系统杀死,融云会认为用户在该客户端离线。用户离线状态下,支持将收到的单聊消息、群聊消息、系统消息、超级群消息通过第三方推送厂商或融云自建的推送服务通知客户端。

  • 如果由第三方厂商推送服务发送提醒,该提醒一般由系统直接弹出,以通知形式展示在通知面板,提示用户收到消息。
  • 如果由融云自建推送通道(RongPush)发送提醒,该提醒一般由 SDK 调用系统 API 构建通知后弹出。注意,RongPush 在国内大部分机型上无法存活。建议应用程序集成第三方厂商的推送服务。

用户点击推送通知后再次与融云服务端建立 IM 连接后,SDK 会有如下行为:

  • 自动收到离线期间的单聊、群聊离线消息?。服务端默认缓存 7 天未收取的离线消息。
  • 自动收到离线期间超级群会话中最后一条消息,应用程序需要自行拉取离线期间的历史消息。

注意

应用程序处于后台且活跃时,用户仍处于在线状态,SDK 仍可实时收到会话消息,消息送达过程中不会使用任何推送服务,因此用户设备不会收到来自任何推送服务的通知。如果使用 IMLib,应用程序需要自行调用系统 API 创建并弹出本地通知。如果使用 IMKit,SDK 默认会调用系统 API 创建并弹出本地通知。

不落地通知

融云支持直接通过服务端 API 向客户端发送远程推送通知,称为不落地通知?。不落地通知中不包含任何会话消息,无论客户端 App 是否在前台,所有通知内容始终仅会以通知形式展示在系统通知栏中,用户无法在任何聊天会话中看到不落地通知的内容。

不落地通知始终通过推送通道下发数据,因此依赖应用程序集成第三方厂商推送服务,或者在客户端启用 RongPush。

  • 如果由第三方厂商推送服务发送提醒,该提醒一般由系统直接弹出,以通知形式展示在通知面板,提示用户收到消息。
  • 如果由融云自建推送通道(RongPush)发送提醒,该提醒一般由 SDK 调用系统 API 构建通知后弹出。注意,RongPush 在国内大部分机型上无法存活。建议应用程序集成第三方厂商的推送服务。

不落地通知仅支持通过服务端 API 发送,例如:

目前不支持通过控制台发送不落地通知(仅部分旧账号仍保留该能力)。

无法推送以及推送受限的情况

  • 因聊天室业务设计特点,仅当聊天室中的用户在线时才会收到聊天室会话中的消息,因此聊天室消息不支持离线消息推送
  • 客户端调用了 logout 方法,或在 disconnect 时设置了不允许推送,或通过设置 SDK 的初始化配置中的 enablePush 参数为 false,向融云服务申请禁用推送服务(当前设备),导致彻底注销用户在融云服务端的登录信息。这种情况下,用户无法通过任何推送通道收到通知。
  • 即使用户的所有移动端设备均已离线,只要用户仍在 Web/PC 端在线,此时融云认为用户在线,默认不会给移动端发送推送通知。如有需要,您可以在控制台免费基础功能页面调整 Web/PC 在线手机端接收 Push 开关设置。
  • 即使用户的移动端应收到推送通知,融云服务端不会向所有已登录过移动端设备均发送推送,仅会向最后一个登录的设备发送推送通知。
  • 已触发第三方厂商推送服务的频率、数量限制。为改善终端用户推送体验,部分第三方推送服务(例如华为、vivo)已对推送消息的分类进行数量和频率管控。建议您充分了解第三方的管理细则。
  • 因超级群业务中普通消息的数量较大,为控制离线推送频率,默认每分钟针对单个用户的单个超级群,每个频道最多产生 1 条推送。默认普通消息累计 2 条时才会触发推送。@ 消息不受此限制。如需调整,详见开通超级群服务

注意

用户必须至少在设备上连接成功过一次,该设备才能接收推送。

注册推送广播接收组件

在主工程的 AndroidManifest.xml 中注册 PushMessageReceiver,用于接收推送相关的事件广播。

    <receiver
android:name="io.rong.push.notification.PushMessageReceiver"
android:exported="true">
<intent-filter>
<action android:name="io.rong.push.intent.MESSAGE_ARRIVED" />
<action android:name="io.rong.push.intent.MESSAGE_CLICKED" />
<action android:name="io.rong.push.intent.THIRD_PARTY_PUSH_STATE" />
</intent-filter>
</receiver>

集成第三方推送

融云支持第三方推送通道。由于国内手机厂商的限制,融云自建推送通道(RongPush)在国内大部分机型上无法存活。您可以优先选择集成第三方推送。第三方推送通道指各手机厂商从系统层维护的长连接通道,您可以与融云提供的推送服务结合使用。

目前融云已适配了小米、华为、荣耀、魅族、OPPO、vivo、FCM 推送服务。

在控制台配置 ApplicationId

融云服务端在向第三方推送通道发送推送数据时,需要使用 App 的应用标识?(Android 应用 ID)。您需要在控制台进行配置。

  1. 访问控制台应用标识页面(也可从服务管理页面左侧 IM 服务下访问)。

    1. 如您有多个融云应用,请确保在页面顶部应用一栏切换到正确的应用。
    2. 新建的应用默认拥有一个应用标识,您可以创建更多应用表示,最多 5 个。每个应用标识均可设置推送,应用标识之间不共享推送配置。
  2. 在应用标识旁,点击设置推送,并在 Android > ApplicationId 一栏填写您的 Android 应用 ID。

    每个 Android 应用均有一个唯一的应用 ID(applicationId),像 Java 软件包名称一样,例如 com.example.myapp。此 ID 可以作为您的应用在设备上和 Google Play 商店中的唯一标识。

    应用 ID 由模块的 build.gradle 文件中的 applicationId 属性定义,如下所示:

    android {
    defaultConfig {
    applicationId "com.example.myapp"
    minSdkVersion 21
    targetSdkVersion 24
    versionCode 1
    versionName "1.0"
    }
    ...
    }

    如果您没有在 build.gradle 中配置 applicationId, 则 applicationId 默认为应用的包名。如果您有更多关于应用 ID 与包名的疑问,可参见 Android 官方文档

集成融云自建推送通道

融云自建推送通道(RongPush)是融云客户端 SDK 与融云推送服务之间维护的一条稳定可靠的长连接通道。属于 SDK 默认推送,不需要额外集成其它三方库即可拥有的基础推送能力。

SDK 初始化启用推送功能后,则自动启用融云自建推送通道(RongPush),App 即具备了基本推送能力,由于国内手机厂商的限制,RongPush 在国内大部分机型上无法存活。建议同时集成第三方推送通道。

从 SDK 5.3.4 版本开始,支持禁用 RongPush,您需要在初始化融云 SDK 之前进行传入推送配置:

PushConfig config = new PushConfig.Builder()
.enableRongPush(false) // 禁用融云自建推送通道
.XXX //此处忽略其它三方推送配置
.build();
RongPushClient.setPushConfig(config); //将推送相关配置设置到 SDK

注意,用户必须至少在设备上连接成功过一次,该设备才能接收推送。

客户端权限配置

由于融云默认推送通道属于应用级别的推送,会受系统各种权限限制,建议提示用户打开对应权限,以提高推送到达率。

推送通道选择策略

在应用配置了多通道的情况下,为了提高用户体验,提高推送到达率,融云客户端 SDK 会根据应用配置,智能选择最优推送通道。

详细启用策略如下:

推送通道配置要求ROM 要求
华为应用配置了华为推送当前设备为华为 ROM
荣耀应用配置了荣耀推送当前设备为荣耀 ROM,且为 2023 年 11 月 30 日后发售的设备。
OPPO应用配置了 OPPO 推送当前设备为以下 ROM 中的一种: OPPO、realme、OnePlus
vivo应用配置了 vivo 推送当前设备为 vivo ROM
魅族应用配置了魅族推送当前设备为魅族 ROM
FCM应用配置了 FCM 推送客户端出访 IP 在国外
RongPush默认推送通道不满足其它通道启用策略,且 RongPush 可用时,默认使用 RongPush 推送通道

注意

关于 FCM 的补充说明

系统原生推送和 FCM 同时配置时,具体使用哪种推送通道,取决于应用层的配置顺序。比如在小米手机上,同时配置了小米推送和 FCM 推送,该用户在国外时:

  • 如果应用层配置时的顺序是小米推送在 FCM 之前,则会启用小米推送。
  • 如果应用层配置时的顺序是 FCM 在小米推送之前,则会启用 FCM 推送。