跳到主要内容

开始集成推送（旧版）

融云 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 端在线，此时融云认为用户在线，默认不会给移动端发送推送通知。如有需要，您可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）调整 Web/PC 在线手机端接收 Push 开关设置。
  • 即使用户的移动端应收到推送通知，融云服务端不会向所有已登录过移动端设备均发送推送，仅会向最后一个登录的设备发送推送通知。
  • 已触发第三方厂商推送服务的频率、数量限制。为改善终端用户推送体验，部分第三方推送服务（例如华为、vivo）中已对推送消息的分类进行数量和频率管控。建议您充分了解第三方的管理细则。
  • 因超级群业务中普通消息的数量较大，为控制离线推送频率，默认每分钟针对单个用户的单个超级群，每个频道最多产生 1 条推送。默认普通消息累计 2 条时才会触发推送。@ 消息不受此限制。。

注意

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

注册推送广播接收组件​

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

xml
    <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 服务功能配置页面（page_code: im_service_config）嵌入到自己的管理后台，然后进入 离线推送 > 应用标识及推送证书管理。

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

  2. 在应用标识旁，点击设置推送，并在 Android > ApplicationId 一栏填写您的 Android 应用 ID。

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

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

    Groovy
    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 之前进行传入推送配置：

Java
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 推送。