跳到主要内容

集成小米推送

按照本指南集成小米 Mi Push 国内版或海外版，让融云 SDK 支持小米推送。

在集成第三方推送前，请确保已在 IM 服务功能配置页面配置 Android 应用 ID。详见推送集成概述。

提示

IMLib SDK 从 5.6.8 开始支持小米国际推送服务。

在内嵌的 IM 服务功能配置页面配置小米推送​

如果想通过小米推送通道从融云服务端接收推送通知，您需要在 IM 服务功能配置页面提供您的小米推送应用的详细信息。

  1. 前往小米开放平台，选择您当前的项目所对应的小米应用，点击应用信息，并记录下应用的 AppID、AppKey、AppSecret。

    提示

    如果没有小米开发者账号，或尚未创建应用，参考小米推送文档：

    (width=600)

    (height=400)

    其中 AppSecret 是小米推送服务器端的身份标识，在使用小米推送服务端 SDK 向客户端发送消息时使用，需要在 IM 服务功能配置页面的小米推送配置中提供给融云。AppId 和 AppKey 是小米推送客户端的身份标识，后续在启用小米推送服务时需要提供给融云 SDK，用于初始化小米推送客户端 SDK。

  2. 在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 离线推送 > 应用标识及推送证书管理 > 设置推送 > Android > 小米推送，填入上一步获取的 AppSecret。

    (height=400)

  3. （可选）配置小米推送通知标题。设置默认的推送通知标题。一般情况下客户端发送消息转 Push 时不使用此标题设置。在调用融云服务端 API /push.json、 /push/user.json、/push/custom.json 接口推送通知时，如未传入通知标题，则使用该处设置的标题。从服务端发消息时，如果发送用户 ID 在融云服务端没有用户名，也会使用此 “推送通知标题”。

  4. 选择推送通道类型。小米推送将消息分为公信消息和私信消息两类:。

    • 公信消息：融云默认使用的小米推送通道，适用于热点新闻、新品推广、平台公告等面向广泛用户群体的内容。有数量限制，详见小米推送消息限制说明。
    • 私信消息：适用于聊天消息、个人订单变化、快递通知、交易提醒等与用户密切相关的通知。推送数量不限，单用户接收数量不限。需要在小米推送运营平台申请私信通道的 channelId 后填入。
    提示

    对于 IM 类应用，建议配置为私信消息通道，以确保聊天消息及时送达且不受数量限制。

  5. （仅对私信消息生效）配置小米推送模板。模板 ID 需从小米推送运营平台获取，然后在 IM 服务功能配置页面中完成配置。融云侧的配置入口和界面说明，参见小米推送模板设置。

    根据小米推送服务最新规定，私信消息需通过模板方式发送，支持使用小米官方模板或自定义模板。详见小米推送官方文档：私信消息模板接入通知、模板接入指南。

    注意

    若您于 2026 年 12 月 31 日前未能完成私信模板接入，将影响私信消息的正常下发。详见模板接入指南。

    在小米推送配置中，支持按推送语言（中文、英文、阿拉伯）和会话类型（单聊、群聊、超级群、系统）的组合设置小米推送模板 ID。同一语言和会话类型组合仅支持设置一个模板 ID。

    此外，还支持配置音视频推送模板，可按推送语言、通话操作（邀请、挂断）和通话类型（音频通话、视频通话）的组合设置模板 ID。

    配置模板后，当消息未携带模板 ID 时，系统将读取此处 App Key 级配置的默认模板进行小米推送，其中模板关键字的值由融云默认填充（详见默认模板关键字填充规则）。

  6. 保存设置。所有设置 15 分钟后生效。

您已完成小米推送服务端配置的全部内容。现在可以设置客户端集成。

设置消息级小米推送模板​

从 Android IMLib 5.46.0 开始，可通过消息的 MessagePushConfig 设置 templateIdMi 和 templateParamMi，为单条消息指定小米私信推送模板。消息级模板信息优先于 App Key 级默认模板；指定模板后，pushTitle 和 pushContent 不再直接决定小米推送的通知标题和内容。配置方法和参数限制详见配置消息推送属性。

默认模板关键字填充规则​

当消息未携带模板 ID 时，系统使用 App Key 级配置的默认模板进行小米推送。此时开发者无需手动传入模板参数，以下关键字由融云服务端自动填充，并由小米推送模板拼接为最终的推送通知。

开发者也可在小米推送运营平台申请自定义模板，自行定义标题和内容的拼接格式。

即时通讯消息模板​

即时通讯消息模板最多使用 3 个关键字，系统根据会话类型自动从消息上下文中提取并填入对应的模板变量：

  • 单聊和系统会话：{$keywords1$} 为发送者名称，{$keywords2$} 为消息内容（截取前 128 个字符）。
  • 群聊和超级群会话：{$keywords1$} 为群名称，{$keywords2$} 为消息发送者名称（群聊 @消息时，[有人@我] 拼接在发送者名称前），{$keywords3$} 为消息内容（截取前 128 个字符）。
  • 当用户设置了多语言推送模板或消息中设置了 title 及 pushContent 时，{$keywords1$} 为 title 内容，{$keywords2$} 为 pushContent 内容。

建议单聊使用小米推送模板 M12378，推送标题结构为 新消息：{$keywords1$}，内容结构为 {$keywords2$}。

建议群聊使用小米推送模板 M10306，推送标题结构为 【群组聊天】{$keywords1$}，内容结构为 {$keywords2$}：{$keywords3$}。

音视频通话模板​

音视频通话模板使用 2 个关键字，系统根据通话类型和用户语言设置自动生成完整的推送标题和正文，直接作为模板变量传入：

  • {$keywords1$} 为完整的推送标题。邀请场景示例："邀请通话"；挂断场景示例："通话结束"。
  • {$keywords2$} 为完整的推送正文。邀请场景示例：{name}邀请您进行语音聊天（有昵称）或“您有一个语音聊天邀请”（无昵称）；挂断场景示例：{name}结束通话（有昵称）或“通话已结束”（无昵称）。

配置客户端接收小米推送​

重要

建议通过 gradle.properties 配置小米的 App ID 与 App Key。如果希望在 App 的 build.gradle 中直接写入配置，请务必额外添加转义符，示例如下：

  • XIAOMI_APP_ID: "\"1882303761517473625\""
  • XIAOMI_APP_KEY : "\"1451747338625\""。

您可以通过以下任意一种方案集成小米推送：

  • 方案一：通过 gradle.properties 配置小米的 App ID 与 App Key。 在 build.gradle 文件 manifestPlaceholders 下 XIAOMI_APP_ID、XIAOMI_APP_KEY 字段中引用 gradle.properties 属性文件中配置。

    gradle.properties 属性文件配置示例：

    MI_PUSH_APPID="9882303761517473625"
    MI_PUSH_APPKEY="9451747338625"

build.gradle 配置示例：

gradle
android {
    defaultConfig {
        manifestPlaceholders = [
                // 小米相关应用参数
                XIAOMI_APP_ID  : "${MI_PUSH_APPID}",
                XIAOMI_APP_KEY : "${MI_PUSH_APPKEY}",
        ]
    }
    // ...其他配置
}

  • 方案二：在 App 的 build.gradle 中添加依赖。

    注意 如果希望在 App 的 build.gradle 中直接写入配置，请务必额外添加转义符，如下所示：

    gradle
    android {
       defaultConfig {
           manifestPlaceholders = [
                   // 小米相关应用参数
                   XIAOMI_APP_ID  : "\"9882303761517473625\""
                   XIAOMI_APP_KEY : "\"9451747338625\"",
           ]
       }
       // ...其他配置
    }

    根据小米推送服务的地域完成相应的配置：

    • 中国大陆地区：集成适用于中国大陆地区的小米推送客户端，并配置小米的 XIAOMI_APP_ID 和 XIAOMI_APP_KEY。

      Groovy
      android {
       defaultConfig {
          //...
          manifestPlaceholders = [
              XIAOMI_APP_ID : "xxxxxxxx",
              XIAOMI_APP_KEY: "xxxxxxxx"
          ]
       }
      }
      dependencies {
          // x.y.z 为当前 IM SDK 版本号
          implementation 'cn.rongcloud.sdk.push:xiaomi:x.y.z'

      }

    • 海外地区：小米在印度孟买、德国法兰克福、俄罗斯莫斯科和新加坡设有数据中心。如果您使用小米海外推送服务，必须集成适用于海外地区的小米推送客户端，并配置小米的 XIAOMI_APP_ID 和 XIAOMI_APP_KEY，和地域。

      Groovy
      android {
       defaultConfig {
          //...
          manifestPlaceholders = [
              XIAOMI_APP_ID : "xxxxxxxx",
              XIAOMI_APP_KEY: "xxxxxxxx",
              XIAOMI_APP_REGION : "" // Global, Europe, Russia, India
          ]
       }
      }
      dependencies {
          // x.y.z 为当前 IM SDK 版本号
          implementation 'cn.rongcloud.sdk.push:xiaomi_global:x.y.z'

      }

启用小米推送服务​

在 SDK init 之前，调用下面代码，初始化 RongPushPlugin 模块。

Java
RongPushPlugin.init(getContext());

如果找不到 RongPushPlugin 模块，请检查是否已经集成融云自建推送通道。

混淆配置​

如果您的应用使用了混淆，您可以使用下面的代码混淆配置：

Groovy
-dontwarn com.xiaomi.mipush.sdk.**
-keep public class com.xiaomi.mipush.sdk.* {*; }

处理推送通知的点击事件​

  • 自定义推送通知点击事件：介绍如何实现 SDK 的默认跳转行为，以及如何自定义处理点击事件。详见自定义推送通知点击事件。
  • 自定义推送通知样式：SDK 接收到其他第三方厂商的推送后，弹出的通知是系统通知，由手机系统底层直接弹出通知，所以不支持自定义。