Skip to main content

Upgrading from IMKit 2.X to 5.X

This document describes the upgrade process from IMKit SDK version 2.X to 5.X.

Upgrade Overview​

The upgrade from IMKit 2.x to 5.x involves changes in the following components. If these features are not used in your implementation, the upgrade can proceed smoothly:

  • RCIM
  • RCMessageCell
  • RCChatSessionInputBarControl
  • RCPluginBoardView
  • Removed conversation settings pages: RCSettingViewController and RCConversationSettingTableViewController
  • RCImagePreviewController
  • RCKitUtility
  • Resource image modifications
  • Message bubble stretch ratio adjustments
  • Migration of RTC resource images
  • Timing for registering custom message cells

Detailed upgrade instructions are provided below.

1. RCIM Interface Changes​

1.1 Configuration Property Migration​

/// Deprecated RCIM interfaces - configurations have been moved to RCKitConfig class
@interface RCIM (Deprecated)

@property (nonatomic, assign) BOOL disableMessageNotificaiton __deprecated_msg("Deprecated. Use RCKitConfigCenter.message.disableMessageNotificaiton instead");

@property (nonatomic, assign) BOOL disableMessageAlertSound __deprecated_msg("Deprecated. Use RCKitConfigCenter.message.disableMessageAlertSound instead");

@property (nonatomic, assign) BOOL enableTypingStatus __deprecated_msg("Deprecated. Use RCKitConfigCenter.message.enableTypingStatus instead");

@property (nonatomic, copy) NSArray *enabledReadReceiptConversationTypeList __deprecated_msg(
"Deprecated. Use RCKitConfigCenter.message.enabledReadReceiptConversationTypeList to configure conversation types with read receipts enabled.");

// ... (Other deprecated properties follow the same pattern)
@end

1.2 Connection Interface Changes​

Key adaptation points when upgrading from 2.x to 5.x:

  1. Remove the token invalid callback logic
  2. Migrate the processing logic to the error callback
// 1. Connection handling
// After calling the interface, if the connection fails due to network issues, 
// the SDK will keep retrying until successful or encountering unrecoverable errors (e.g., invalid token, banned user)
[[RCIM sharedRCIM] connectWithToken:newToken
        dbOpened:^(RCDBErrorCode code) {
            // Message database opened, proceed to main interface
        }
        success:^(NSString *userId) {
            // Connection successful
        }
        error:^(RCConnectErrorCode status) {
            if (status == RC_CONN_TOKEN_INCORRECT) {
                // Retrieve new token from app server and reconnect
            } else {
                // Handle connection failures based on error codes
            }
        }]

// Alternatively with timeout:
[[RCIM sharedRCIM] connectWithToken:token
    timeLimit:5
    dbOpened:^(RCDBErrorCode code) {
        // Message database opened
    } success:^(NSString *userId) {
        // Connection successful
    } error:^(RCConnectErrorCode status) {
        if (status == RC_CONN_TOKEN_INCORRECT) {
            // Retrieve new token
        } else if(status == RC_CONNECT_TIMEOUT) {
            // Connection timeout - prompt user to retry when network improves
        } else {
            // Handle other connection errors
        }
    }]

// 2. Connection status monitoring
// Recommended to implement in a singleton class (e.g., AppDelegate)
[[RCIM sharedRCIM] addConnectionStatusDelegate:self];

- (void)onRCIMConnectionStatusChanged:(RCConnectionStatus)status {
    if (status == ConnectionStatus_KICKED_OFFLINE_BY_OTHER_CLIENT) {
        // User logged in elsewhere - notify and handle accordingly
    } else if (status == ConnectionStatus_DISCONN_EXCEPTION) {
        // User banned - notify and handle accordingly
    }
}

Note

In the new connection interface:

  • Intermediate error codes that can self-recover (e.g., RC_NET_CHANNEL_INVALID) no longer trigger onError callbacks
  • Unlike the old version, post onError triggering, versions 4.0.0+ will not attempt reconnection
  • The SDK only triggers onError for unrecoverable errors

1.3 Read Receipt Notification Change​

FOUNDATION_EXPORT NSString *const
    RCKitDispatchReadReceiptNotification __deprecated_msg("Deprecated. Use RCLibDispatchReadReceiptNotification instead.");

1.4 Image Message Sending Interface Deprecation​

Upgrade note: Replace with sendMediaMessage:targetId:content:pushContent:pushData:success:error:cancel: for identical functionality.

- (RCMessage *)sendImageMessage:(RCConversationType)conversationType
                       targetId:(NSString *)targetId
                        content:(RCMessageContent *)content
                    pushContent:(NSString *)pushContent
                       pushData:(NSString *)pushData
                       progress:(void (^)(int progress, long messageId))progressBlock
                        success:(void (^)(long messageId))successBlock
                          error:(void (^)(RCErrorCode errorCode, long messageId))errorBlock
    __deprecated_msg("Deprecated. Use sendMediaMessage instead.");

1.5 Read Receipt Enable Interface Deprecation​

@property (nonatomic, assign) BOOL enableReadReceipt __deprecated_msg(
    "Deprecated. Use enabledReadReceiptConversationTypeList to configure conversation types with read receipts enabled.");

2. RCMessageCell Changes​

@property (nonatomic, strong) UIView *messageHasReadStatusView;

This deprecated property has been removed. Use the existing statusContentView instead.

3. RCChatSessionInputBarControl Changes​

Removed delegate method:

- (void)imageDidSelect:(NSArray *)selectedImages fullImageRequired:(BOOL)full __deprecated_msg("Deprecated. Do not use.");

Replacement method:

- (void)imageDataDidSelect:(NSArray *)selectedImages fullImageRequired:(BOOL)full;

Note: All enums in RCChatSessionInputBarControl have been migrated to RCExtensionKitDefine.

4. RCPluginBoardView Changes​

All methods for inserting/updating extension panel buttons now include a highlightedImage parameter to support pressed states:

/*!
 Insert an extension item into the plugin board
 
 @param normalImage       Default display image
 @param highlightedImage  Pressed state image  
 @param title            Display title
 @param index            Insertion index
 @param tag              Unique identifier
 
 @discussion Add custom items after RCConversationViewController's viewdidload.
 Avoid using 1XXX tags which are reserved for SDK default items.
 */
- (void)insertItem:(UIImage *)normalImage highlightedImage:(UIImage *)highlightedImage title:(NSString *)title atIndex:(NSInteger)index tag:(NSInteger)tag;

// ... (Other updated methods follow similar pattern)

5. Removed Setting Page Classes​

RCSettingViewController and RCConversationSettingTableViewController have been removed. For reference implementations, see the official SealTalk demo source code (RCDSettingViewController, RCDPrivateSettingsTableViewController, and RCDGroupSettingsTableViewController).

6. RCImagePreviewController Replacement​

The deprecated RCImagePreviewController (single image preview) should be replaced with RCImageSlideController:

RCImageSlideController *imagePreviewVC = [[RCImageSlideController alloc] init];
imagePreviewVC.messageModel = model;
imagePreviewVC.onlyPreviewCurrentMessage = YES; // NO enables gallery-style preview
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:imagePreviewVC];
nav.modalPresentationStyle = UIModalPresentationFullScreen;
[self presentViewController:nav animated:YES completion:nil];

7. RCKitUtility Method Removal​

This utility method has been removed. Use equivalent methods in RCAlertView instead:

+ (void)showAlertController:(NSString *)title
                    message:(NSString *)message
             preferredStyle:(UIAlertControllerStyle)style
                    actions:(NSArray<UIAlertAction *> *)actions
           inViewController:(UIViewController *)controller;

8. Resource Image Naming Changes​

  • Plugin board images now use "plugin_item_" prefix
  • Input bar icons now use "inputbar_" prefix naming convention
  • If you've previously replaced these resources, update your image names accordingly

9. Message Bubble Stretch Ratio Adjustment​

// Original stretch insets:
UIEdgeInsetsMake(image.size.height * 0.8, image.size.width * 0.2, image.size.height * 0.2, image.size.width * 0.8)

// New stretch insets:  
UIEdgeInsetsMake(image.size.height * 0.5, image.size.width * 0.5, image.size.height * 0.5, image.size.width * 0.5)

10. RTC Resource Migration​

RongIMKit no longer contains RTC-related resources (images/localization files). These have been moved to the RongCallKit library.

11. Custom Message Cell Registration Timing​

For custom message cells, registration must occur first in the conversation view controller's viewDidLoad before any other operations.

Last updated on