Skip to main content

IMKit 4.X Compatibility with 5.X IMLib Solution

This document explains how to upgrade to the 5.X version of IMLib (RC Chat capability library) while maintaining the 4.X version of IMKit in your project, achieving version compatibility between UI components and core functionalities.

Solution Overview​

By using the im_compat compatibility package, you can leverage the latest features and performance optimizations of 5.X IMLib while retaining the 4.X IMKit UI components. This approach is ideal for projects that require UI stability but need access to advanced core functionalities.

Dependency Structure​

im_kit:4.2.0 depends on the im_compat:4.2.1 compatibility package, which automatically includes the 5.X version of the IMLib core capability library.

The default dependency tree is structured as follows:

─ 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
note

The compatibility package defaults to the stable version 5.7.5. You can also customize the version based on project requirements.

Implementation Guide​

1. Add Repositories and Dependencies​

In your module's build.gradle file, add the Maven Central repository and the im_kit dependency.

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. Initialization Configuration​

The initialization process remains consistent with IMKit 4.X and requires no additional configuration:

RongIM.init(this);  
RongIM.connect(token, new RongIMClient.ConnectCallback() {  
    @Override  
    public void onSuccess(String userId) {  
        // Connection successful  
    }  
    
    @Override  
    public void onError(RongIMClient.ErrorCode errorCode) {  
        // Connection failed  
    }  
    
    @Override  
    public void onTokenIncorrect() {  
        // Invalid Token  
    }  
});

3. Adapt to API Changes​

After upgrading, you need to adapt to certain API changes, primarily the onReceived method of the message receiver listener.

RongIM.setOnReceiveMessageListener(new RongIMClient.OnReceiveMessageListener() {  

    // This method is deprecated and will no longer be triggered  
    @Override  
    public boolean onReceived(Message message, int left) {  
        return false;  
    }  
    
    // Replace with the new onReceived method  
    @Override  
    public boolean onReceived(Message message, int left, boolean hasPackage, boolean offline) {  
        return false;  
    }  
});
important

After upgrading to 5.X IMLib, you must use the new onReceived method signature. The old method will no longer work.

Customize IMLib Module Versions​

If the default IMLib version (stable 5.7.5) does not meet your requirements, you can customize all 5.X module versions as follows:

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

// 1. Exclude all default arouter-api modules from im_compat  
implementation('cn.rongcloud.sdk:im_compat:4.2.1') {  
    exclude group: 'cn.rongcloud.sdk'  
}  

// 2. Import custom versions of IMLib modules as needed  
def customVersion = "5.12.3" // Your desired version  
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"

Push Notification Plugin Configuration​

important

We recommend retaining your existing push notification configuration. If your project has not yet integrated push functionality, consider using the Push 2.0 integration solution.

Legacy Push Integration​

If you still need to use the legacy push solution, refer to the Legacy Push Integration Guide for configuration.

dependencies {  
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'  
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'  
    
    // Use the 4.2.0 push plugin series (for Support library projects)  
    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"  
}

Push 2.0 Integration​

If you plan to use Push 2.0, refer to the Push 2.0 Integration Guide for configuration.

AndroidX Project Integration​

dependencies {  
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'  
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'  
    
    // Use the 5.X push plugin series  
    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 Library Project Integration​

dependencies {  
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'  
    implementation 'cn.rongcloud.sdk:im_compat:4.2.1'  
    
    // Use the 4.2.0 push plugin series (for Support library projects)  
    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"  
}
caution
  • AndroidX Projects: Can use any 5.X version of push plugins.
  • Support Library Projects: Only support the 4.2.0 version of push plugins. Support library projects do not support the Google push plugin cn.rongcloud.sdk.push:fcm.
  • Minimum Version Requirement: The project's minSdkVersion must be set to 21 or higher.

Rollback Solution​

If you encounter unresolvable compatibility issues during adaptation, you can easily revert to the pure 4.X solution:

dependencies {  
    implementation 'cn.rongcloud.sdk:im_kit:4.2.0'  
    implementation 'cn.rongcloud.sdk:im_lib:4.2.0'  // Revert to 4.X core library  
}

Compatibility Notes​

  • UI Interface: Fully retains the 4.X IMKit UI style and interaction patterns.
  • API Interface: Most 4.X APIs remain unchanged, with only minor interfaces requiring adaptation.
  • Features: Directly supports all new 5.X IMLib features (e.g., ultra groups) and performance optimizations.
  • Stability: The solution has been thoroughly tested to ensure compatibility and stability.

Version Selection Recommendations​

  • New Projects: We recommend directly using the latest IMKit 5.X version for comprehensive features and optimal performance.
  • Existing Projects: If your project is already live and requires UI stability, this solution enables a smooth core library upgrade.
  • Feature-Driven Needs: Ideal for projects that need 5.X core functionalities without extensive UI refactoring.

FAQs​

Q: Does upgrading require extensive code changes?​

A: No. Most code remains unchanged. Only minor interface adaptations are needed, such as the message receiver listener.

Q: How is the performance?​

A: The core library is upgraded to 5.X, so performance is on par with IMKit 5.X and significantly improved over 4.X.

Q: Are all 5.X new features supported?​

A: All core functionalities of 5.X IMLib are supported, but the UI layer retains 4.X features.

Q: How to handle compatibility issues?​

A: If issues arise, first try customizing IMLib module versions or reverting to the 4.X solution.

Last updated on