跳到主要内容

集成融云推送插件

融云提供的推送插件，依赖 WebLib SDK，开发者在集成推送插件前必须集成了 WebLib SDK 或 uni-app 的 IMKit SDK。

集成步骤​

1. 集成插件​

  1. 点击打开 RCIM-Push-Wrapper，点击 下载插件并导入 HBuilderX 按钮，将插件导入项目中。

  2. 导入成功后，在项目根目录下可看到 uni_modules 目录下有 RCIM-Push-Wrapper 和 RCIM-Push 目录，如下图所示：

    uni模块目录结构

2. 配置 Android 推送​

在您的 uni-app 项目根目录创建以下文件结构：

nativeResources/
  └── android/
      └── manifestPlaceholders.json

在 manifestPlaceholders.json 文件中配置 Android 推送参数。如果该文件已存在，直接添加相关配置即可。

将以下内容添加到 manifestPlaceholders.json 文件中：

JSON
{
  "XIAOMI_APP_ID": "",
  "XIAOMI_APP_KEY": "",
  "HW_PUSH_ENABLE" : "false",
  "HONOR_APP_ID": "",
  "OPPO_APP_KEY": "",
  "OPPO_APP_SECRET": "",
  "VIVO_APP_ID": "",
  "VIVO_APP_KEY": "",
  "MEIZU_APP_ID": "",
  "MEIZU_APP_KEY": "",
  "FCM_PUSH_ENABLE": "false"
}

小米推送​

  1. 参考在控制台配置小米推送配置小米推送信息。
  2. 在 manifestPlaceholders.json 文件中配置 XIAOMI_APP_ID 和 XIAOMI_APP_KEY。

华为推送​

  1. 参考在控制台配置华为推送配置华为推送信息。

  2. 在 manifestPlaceholders.json 文件中配置 HW_PUSH_ENABLE 为 true。

  3. 根据华为开发者文档集成 HMS Core SDK，您需要将 "agconnect-services.json" 文件添加到您的 App 中。点击 agconnect-services.json 下载配置文件。

    agconnect-services.json

  4. 将下载好的 agconnect-services.json 文件放到项目 nativeResources/android 目录下，如下图：

    agconnect-services.json 路径

荣耀推送​

  1. 参考在控制台配置荣耀推送配置荣耀推送信息。

  2. 在 manifestPlaceholders.json 文件中配置 HONOR_APP_ID。

  3. 登录荣耀开发者服务平台，单击应用管理，在应用列表中找到目标应用，单击应用详情。在应用基础信息查看页面的 SDK 配置区域，下载 mcs-services.json 配置文件。

    mcs-services.json

  4. 将下载好的 mcs-services.json 文件拷贝到项目 nativeResources/android 目录下，如下图：

    mcs-services.json 路径

OPPO 推送​

  1. 参考在控制台配置 OPPO 推送配置 OPPO 推送信息。
  2. 在 manifestPlaceholders.json 文件中配置 OPPO_APP_KEY 和 OPPO_APP_SECRET。

VIVO 推送​

  1. 参考在控制台配置 vivo 推送配置 vivo 推送信息。
  2. 在 manifestPlaceholders.json 文件中配置 VIVO_APP_ID 和 VIVO_APP_KEY。

魅族推送​

  1. 参考在控制台配置魅族推送配置魅族推送信息。
  2. 在 manifestPlaceholders.json 文件中配置 MEIZU_APP_ID 和 MEIZU_APP_KEY。

FCM 推送​

  1. 参考 在控制台授权 FCM 请求 在控制台上传 FCM 凭证。

  2. 在 manifestPlaceholders.json 文件中配置 FCM_PUSH_ENABLE 为 true。

  3. 在 Firebase 控制台 点击 下载 google-services.json 以获取 Firebase Android 配置文件 (google-services.json)。

  4. 将下载好的 google-services.json 文件拷贝到项目 nativeResources/android 目录下，如下图：

    google-services.json 路径

3. 配置 iOS 推送​

  1. 了解 融云服务端对 APNs 的支持。
  2. 参考 Apple 开发者账户的操作 创建推送证书。
  3. 参考 在融云控制台配置 APNs 推送。
  4. 参考 创建 Provisioning Profile 文件 创建 Provisioning Profile 文件，并使用该文件打包 app。

4. 勾选 Push 模块​

在项目根目录下，点击 manifest.json > 安卓/iOS模块配置 > 打包模块配置 ，勾选 Push(消息推送) 模块，无需勾选 uniPush 1.0 和 uniPush 2.0。

勾选后如下图所示：

push 模块

5. 制作自定义调试基座​

使用推送插件必须制作自定义调试基座，点击 HBuilderX 菜单栏的 运行 > 运行到手机或模拟器，选择 制作自定义调试基座 选项，使用相应的证书制作 Android 或 iOS 自定义调试基座。

使用步骤​

1. 导入推送插件​

示例如下：

JavaScript
import * as RCPush from '@/uni_modules/RCIM-Push-Wrapper'

2. 添加推送回调事件​

在调用 registerPush 方法注册推送前，即可添加推送回调事件。

以下回调事件开发者可根据自己需要选择添加。

点击查看推送回调事件

获取推送标识回调事件​

开发者可通过 setOnPushTokenReceivedListener 方法监听获取推送标识回调事件。

当获取到推送标识后，会触发该回调事件。开发者如需使用其他三方推送时，可通过此回调获取到设备推送标识。

JavaScript
RCPush.setOnPushTokenReceivedListener((res) => {
  if (res.code === 0) {
    // 获取推送标识成功
    const { pushType, token } = res.data;
    // pushType 为推送类型，token 为推送标识
  } else {
    // 获取推送标识失败
    console.error(res.message);
  }
});

推送消息点击回调事件​

开发者可通过 setOnPushClickedListener 方法监听推送消息点击回调事件。

当收到推送消息时，点击推送消息，会触发该回调事件。

提示
  • iOS 端仅在 app 关闭时点击推送打开 app 后才会触发该回调事件。
  • Android 端在 IM 断开连接后，app 无论是关闭还是打开状态，点击推送消息都会触发该回调事件。
JavaScript
RCPush.setOnPushClickedListener((res) => {
  if (res.code === 0) {
    // 推送消息点击成功
  } else {
    // 推送消息点击失败
    console.error(res.message);
  }
});

推送标识上报结果回调事件​

开发者可通过 setOnPushTokenReportResultListener 方法监听推送标识上报是否成功。

当推送标识上报结果回调事件触发时，会触发该回调事件。开发者可通过该回调事件获取到推送标识上报结果。

提示
  • 只有 Android 端会回调此事件，iOS 端不会触发此回调。
  • 推送标识上报成功后，该事件只会触发一次，如果推送标识或用户信息未发生变化，则不会重复上报推送标识。
JavaScript
RCPush.setOnPushTokenReportResultListener((res) => {
  if (res.code === 0) {
    // 推送标识上报成功
  } else {
    // 推送标识上报失败
    console.error(res.message);
  }
});

3. 注册推送​

在 WebLib 调用 init 之后，调用 connect 接口连接 IM 之前，调用 registerPush 方法注册推送。

切换用户时无需重复调用 registerPush 方法，SDK 会自动处理用户切换时的逻辑。

为了便于开发者调试，在注册推送时可通过 logLevel 设置控制台日志输出级别。默认级别为 2，输出警告日志。

点击查看日志级别
日志级别描述
0不输出日志
1输出错误日志
2输出警告日志
3输出信息日志
4输出调试日志

调用示例如下：

JavaScript
// 初始化 IM
RongIMLib.init({appKey: 'xxx'});

// 注册推送
RCPush.registerPush({ logLevel: 4 }).then(res => {
    if (res.code === 0) {
      // 注册推送成功
    } else {
      // 注册推送失败
      console.error(res.message);
    }
});

// 连接 IM
RongIMLib.connect().then(res => {
    if (res.code === 0) {
      // 连接 IM 成功
    } else {
      // 连接 IM 失败
    }
});

4. 断开连接​

在断开连接时，不设置任何参数默认为断开连接后接收离线推送。

可设置 disablePush 为 true 表示用户断开连接后不再接收离线推送。

调用示例如下：

JavaScript
// 断开连接后默接收离线推送
RongIMLib.disconnect();

// disablePush 在第二个参数，true 表示断开连接时不再接收推送。第一个参数传 null 即可。
RongIMLib.disconnect(null, true);

5. 测试消息推送​

建议先使用比较简单的单聊场景测试推送。步骤如下：

  1. 按照以上步骤配置并注册推送后，重新自定义调试基座运行 app，在连接 IM 成功后查看推送标识上报结果回调是否成功，如成功，则表示推送配置成功。 确认配置成功后杀掉 App 进程。
  2. 在需先按控制台内嵌指南嵌入到管理后台的 IM Server API 调试页面（page_code: im_server_api）中，找到消息>消息服务>发送单聊消息，直接给当前应用用户发送一条单聊消息内容。
  3. 查看手机是否收到推送。

故障排查​

如果未能收到推送，请先检查以下项目：

  • 如果客户端断开连接时设置了不允许推送，例如调用 disconnect(null, true) 方法，则会彻底注销在融云服务端的登录信息。融云服务端仅记录离线消息，但不会触发推送服务。
  • 如果 App 用户已在 Web/PC 端在线，此时融云认为用户在线，默认不会给移动端发送推送通知。如有需要，您可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 离线推送 调整 Web/PC 在线手机端接收 Push 开关设置。
  • 如果同一用户账号在多台移动设备上同时登录，融云服务端仅向最后一个登录的设备发送推送通知。

您可以通过融云控制台的「北极星」查看消息发送与接收状态，以及具体的推送错误：

  1. 访问控制台的「北极星」消息流转页面，切换到正确的环境（开发/生产）中，根据页面提供的搜索条件搜索消息，点击查询。

  2. 在查询结果页面，找到需要排障的消息，点击「接收状态」栏中的查看。

  3. 在目标用户消息接收状态下，检查消息已通过推送下发给消息收件人。如果出现问题，该页面会显示具体原因。

  4. 您可以在推送错误码知识库中查询北极星消息流转返回的全部推送错误码。

  5. 如果问题持续，可直接提交工单，提供您的消息 ID 与查询结果。