跳到主要内容

IMKit 4.X 适配 5.X IMLib 方案

本文介绍如何在项目中保持 IMKit 4.X 版本的同时，升级并使用 5.X 版本的 IMLib（即时通讯能力库），从而实现 UI 组件与核心功能的版本兼容。

方案概述​

通过 im_compat 兼容包，您可以在使用 IMKit 4.X UI 组件的同时，享受 5.X IMLib 的最新功能和性能优化。这种方案特别适合希望保持现有 UI 稳定性，但需要使用最新核心功能的项目。

依赖关系​

im_kit:4.2.0 依赖了 im_compat:4.2.1 兼容包，该兼容包会自动引入 5.X 版本的 IMLib 核心能力库。

默认的依赖树结构如下：

─ im_kit:4.2.0
   └─ im_compat:4.2.1
      ├─ im_libcore:5.7.10
      ├─ im_chatroom:5.7.10
      ├─ im_location:5.7.10
      ├─ im_discussion:5.7.10
      ├─ im_customservice:5.7.10
      └─ im_publicservice:5.7.10
备注

兼容包默认依赖稳定版 5.7.5，您也可以根据项目需求自定义版本。

用户接入指南​

1. 添加仓库和版本依赖​

在模块的 build.gradle 文件中，添加 Maven Central 仓库和 im_kit 依赖。

gradle
repositories {
    maven { url "https://maven.rongcloud.cn/repository/maven-releases/" }
}

dependencies {
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0' 
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'
}

2. 初始化配置​

初始化方式与 IMKit 4.X 版本保持一致，无需额外配置：

Java
RongIM.init(this);
RongIM.connect(token, new RongIMClient.ConnectCallback() {
    @Override
    public void onSuccess(String userId) {
        // 连接成功
    }
    
    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {
        // 连接失败
    }
    
    @Override
    public void onTokenIncorrect() {
        // Token 错误
    }
});

3. 适配接口变更​

升级后，您需要适配部分 API 的变更，最主要是消息接收监听器的 onReceived 方法。

Java
RongIM.setOnReceiveMessageListener(new RongIMClient.OnReceiveMessageListener() {

    // 此方法已废弃，不再回调
    @Override
    public boolean onReceived(Message message, int left) {
        return false;
    }
    
    // 请替换为新的 onReceived 方法
    @Override
    public boolean onReceived(Message message, int left, boolean hasPackage, boolean offline) {
        return false;
    }
});
important

升级到 5.X IMLib 后，必须使用新的 onReceived 方法签名，旧方法将失效。

自定义 IMLib 模块版本​

如果默认的 IMLib 版本（稳定版 5.7.5）不满足您的需求，可以通过以下方式自定义所有 5.X 模块的版本：

gradle
build.gradle
implementation 'cn.rongcloud.sdk:im_kit:4.2.0'

// 1. 排除 im_compat 默认依赖的所有 arouter-api 模块
implementation('cn.rongcloud.sdk:im_compat:4.2.1') {
    exclude group: 'cn.rongcloud.sdk'
}

// 2. 按需引入自定义版本的 IMLib 模块
def customVersion = "5.12.3" // 您期望的版本
implementation "cn.rongcloud.sdk:im_libcore:$customVersion"
implementation "cn.rongcloud.sdk:im_chatroom:$customVersion"
implementation "cn.rongcloud.sdk:im_location:$customVersion"
implementation "cn.rongcloud.sdk:im_discussion:$customVersion"
implementation "cn.rongcloud.sdk:im_customservice:$customVersion"
implementation "cn.rongcloud.sdk:im_publicservice:$customVersion"

推送插件配置​

important

我们建议您保持原有工程的推送配置。如果您的工程尚未集成推送功能，可以考虑使用推送 2.0集成方案。

推送（旧版）集成方案​

如果您仍需使用旧版推送，请参考 推送（旧版）集成指南 进行配置。

gradle
dependencies {
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'
    
    // 使用 4.2.0 推送插件系列（支持库专用）
    def pushVersion = "4.2.0"
    implementation "cn.rongcloud.sdk.push:rong:$pushVersion"
    implementation "cn.rongcloud.sdk.push:huawei:$pushVersion"
    implementation "cn.rongcloud.sdk.push:xiaomi:$pushVersion"
    implementation "cn.rongcloud.sdk.push:oppo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:vivo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:meizu:$pushVersion"
    implementation "cn.rongcloud.sdk.push:honor:$pushVersion"
}

推送 2.0 集成方案​

如果您计划使用推送 2.0，请参考 开始集成推送 2.0 文档进行配置。

AndroidX 工程接入方案​

gradle
dependencies {
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'
    
    // 使用 5.X 推送插件系列
    def pushVersion = "5.7.5"
    implementation "cn.rongcloud.sdk.push:rong:$pushVersion"
    implementation "cn.rongcloud.sdk.push:huawei:$pushVersion"
    implementation "cn.rongcloud.sdk.push:xiaomi:$pushVersion"
    implementation "cn.rongcloud.sdk.push:oppo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:vivo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:meizu:$pushVersion"
    implementation "cn.rongcloud.sdk.push:honor:$pushVersion"
}

Support 库工程接入方案​

gradle
dependencies {
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'
    
    // 使用 4.2.0 推送插件系列（支持库专用）
    def pushVersion = "4.2.0"
    implementation "cn.rongcloud.sdk.push:rong:$pushVersion"
    implementation "cn.rongcloud.sdk.push:huawei:$pushVersion"
    implementation "cn.rongcloud.sdk.push:xiaomi:$pushVersion"
    implementation "cn.rongcloud.sdk.push:oppo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:vivo:$pushVersion"
    implementation "cn.rongcloud.sdk.push:meizu:$pushVersion"
    implementation "cn.rongcloud.sdk.push:honor:$pushVersion"
}
警告
  • AndroidX 工程：可使用任意 5.X 版本的推送插件。
  • Support 库工程：仅支持 4.2.0 版本的推送插件。Support 库工程不支持谷歌推送插件 cn.rongcloud.sdk.push:fcm。
  • 最低版本要求：工程的 minSdkVersion 必须设置为 21 或更高版本。

回退方案​

如果在适配过程中遇到难以解决的兼容性问题，可以方便地回退到纯 4.X 方案：

gradle
dependencies {
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'
    implementation 'cn.rongcloud.sdk:im_lib:4.2.0'  // 替换为 4.X 核心库
}

兼容性说明​

  • UI 界面：完全保持 IMKit 4.X 的 UI 风格和交互方式。
  • API 接口：绝大部分 4.X API 保持不变，仅有少量接口需要适配。
  • 功能特性：可直接使用 5.X IMLib 的新功能（如超级群）和性能优化。
  • 稳定性：方案经过充分测试，可确保兼容性和稳定性。

版本选择建议​

  • 新项目：我们建议直接使用最新的 IMKit 5.X 版本，以使用完整功能并获得出色的性能。
  • 现有项目：如果项目已上线且希望保持 UI 稳定性，可采用本方案平滑升级核心库。
  • 功能驱动：如果需要使用 5.X 的核心功能但不想大规模重构 UI，可采用本方案。

常见问题​

问：升级后需要修改大量代码吗？​

答：不需要。绝大部分代码可保持原样，仅需适配极少量接口变更，例如消息接收监听器。

问：性能表现如何？​

答：核心库已升级至 5.X 版本，因此性能表现与 IMKit 5.X 基本一致，相较于 4.X 版本有显著提升。

问：是否支持所有 5.X 的新功能？​

答：支持 5.X IMLib 的所有核心功能，但 UI 层面仍保持 4.x 的已有特性。

问：如何处理兼容性问题？​

答：如遇到问题，您可以优先尝试自定义 IMLib 模块版本，或直接回退到 4.X 方案来解决。