跳到主要内容

IMKit 2.X 升级到 5.X

本文描述 IMKit SDK 从 2.X 到 5.X 版本的升级步骤。

升级概述

从 2.x IMKit 升级到 5.x 版本,涉及到以下相关内容的变更,如果没用到以下内容可以平滑升级:

  • RCIM
  • RCMessageCell
  • RCChatSessionInputBarControl
  • RCPluginBoardView
  • 会话设置页删除:RCSettingViewController 和RCConversationSettingTableViewController
  • RCImagePreviewController
  • RCKitUtility
  • 资源图片变动
  • 消息气泡拉伸比例修改
  • 音视频资源图片迁移
  • 注册自定义消息 cell 时机

以下是详细的升级说明。

1. RCIM 的接口

1.1 配置属性调用类变更

/// RCIM 的废弃接口,配置已被移动到 RCKitConfig 类中
@interface RCIM (Deprecated)

@property (nonatomic, assign) BOOL disableMessageNotificaiton __deprecated_msg("已废弃,请使用 RCKitConfigCenter.message.disableMessageNotificaiton");

@property (nonatomic, assign) BOOL disableMessageAlertSound __deprecated_msg("已废弃,请使用 RCKitConfigCenter.message.disableMessageAlertSound");

@property (nonatomic, assign) BOOL enableTypingStatus __deprecated_msg("已废弃,请使用 RCKitConfigCenter.message.enableTypingStatus");

@property (nonatomic, copy) NSArray *enabledReadReceiptConversationTypeList __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enabledReadReceiptConversationTypeList,设置开启回执的会话类型。");

@property (nonatomic, assign) NSUInteger maxReadRequestDuration __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.maxReadRequestDuration");

@property (nonatomic, assign) BOOL enableSyncReadStatus __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableSyncReadStatus");

@property (nonatomic, assign) BOOL enableMessageMentioned __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableMessageMentioned");

@property (nonatomic, assign) BOOL enableMessageRecall __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableMessageRecall");

@property (nonatomic, assign) NSUInteger maxRecallDuration __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.maxRecallDuration");

@property (nonatomic, assign) BOOL showUnkownMessage __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.showUnkownMessage");

@property (nonatomic, assign) BOOL showUnkownMessageNotificaiton __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.showUnkownMessageNotificaiton");

@property (nonatomic, assign) NSUInteger maxVoiceDuration __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.maxVoiceDuration");

@property (nonatomic, assign) BOOL isExclusiveSoundPlayer __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.isExclusiveSoundPlayer");

@property (nonatomic, assign) BOOL isMediaSelectorContainVideo __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.isMediaSelectorContainVideo");

@property (nonatomic, assign) NSInteger GIFMsgAutoDownloadSize __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.GIFMsgAutoDownloadSize");

@property (nonatomic, assign) BOOL enableSendCombineMessage __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableSendCombineMessage");

@property (nonatomic, assign) BOOL enableBurnMessage __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableDestructMessage");

@property (nonatomic, assign) NSUInteger reeditDuration __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.reeditDuration");

@property (nonatomic, assign) BOOL enableMessageReference __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.enableMessageReference");

@property (nonatomic, assign) NSUInteger sightRecordMaxDuration __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.message.sightRecordMaxDuration");

@property (nonatomic, strong) UIColor *globalNavigationBarTintColor __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.globalNavigationBarTintColor");

@property (nonatomic, assign) RCUserAvatarStyle globalConversationAvatarStyle __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.globalConversationAvatarStyle");

@property (nonatomic, assign) CGSize globalConversationPortraitSize __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.globalConversationPortraitSize");

@property (nonatomic, assign) RCUserAvatarStyle globalMessageAvatarStyle __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.globalMessageAvatarStyle");

@property (nonatomic, assign) CGSize globalMessagePortraitSize __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.globalMessagePortraitSize");

@property (nonatomic, assign) CGFloat portraitImageViewCornerRadius __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.portraitImageViewCornerRadius");

@property (nonatomic, assign) BOOL enableDarkMode __deprecated_msg(
"已废弃,请使用 RCKitConfigCenter.ui.enableDarkMode");
@end

1.2 连接接口变更

从 2.x 版本升级到 5.x, 关键适配点是删除连接接口 token 非法的回调,并将该回调中的处理逻辑,移动至 error 回调中,代码示例如下:

//1.连接处理
//用户调用接口之后,如果因为网络原因暂时连接不上,SDK 会一直尝试重连,直到连接成功或者出现 SDK 无法处理的错误(如 token 非法,用户封禁等)
[[RCIM sharedRCIM] connectWithToken:newToken
dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
}
success:^(NSString *userId) {
//连接成功
}
error:^(RCConnectErrorCode status) {
if (status == RC_CONN_TOKEN_INCORRECT) {
//从 APP 服务获取新 token,并重连
} else {
//无法连接到 IM 服务器,请根据相应的错误码作出对应处理
}
}]
//或者
//用户调用接口之后,SDK 会在 timeLimit 秒内尝试连接,超过时间将会返回超时并停止连接,timeLimit <= 0 行为和没有 timeLimit 的接口一样
[[RCIM sharedRCIM] connectWithToken:token
timeLimit:5
dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
} success:^(NSString *userId) {
//连接成功
} error:^(RCConnectErrorCode status) {
if (status == RC_CONN_TOKEN_INCORRECT) {
//从 APP 服务获取新 token,并重连
} else if(status == RC_CONNECT_TIMEOUT) {
//连接超时,弹出提示,可以引导用户等待网络正常的时候再次点击进行连接
} else {
//无法连接 IM 服务器,请根据相应的错误码作出对应处理
}
}]

//2.连接状态监听设置

//其中 self 最好为单例类(如 AppDelegate),以此保证在整个 APP 生命周期,该类都能够检测到 SDK 连接状态的变更
[[RCIM sharedRCIM] addConnectionStatusDelegate:self];

- (void)onRCIMConnectionStatusChanged:(RCConnectionStatus)status {
if (status == ConnectionStatus_KICKED_OFFLINE_BY_OTHER_CLIENT) {
//当前用户账号在其他端登录,请提示用户并做出对应处理
} else if (status == ConnectionStatus_DISCONN_EXCEPTION) {
//用户被封禁,请提示用户并做出对应处理
}
}

注意

新增的连接接口,可自行重连的中间错误码将不再触发 onError 回调(如旧版的 RC_NET_CHANNEL_INVALID 等),只有发生 SDK 无法处理的错误才会触发 onError 回调。 跟旧版的另外一个区别是,onError 回调触发后,4.0.0 及之后版本将不再重连。而旧版 SDK 在出现可自行重连的中间错误码触发 onError 回调后,还会进行自动重连。

1.3 收到已读回执通知

FOUNDATION_EXPORT NSString *const
RCKitDispatchReadReceiptNotification __deprecated_msg("已废弃,请使用RCLibDispatchReadReceiptNotification通知。");

1.4 图片消息发送接口废弃

升级说明:如果您之前使用了此接口,可以直接替换为sendMediaMessage:targetId:content:pushContent:pushData:success:error:cancel:接口,行为和实现完全一致。

- (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("已废弃,请使用sendMediaMessage函数。");

1.5 开启已读回执功能接口废弃

@property (nonatomic, assign) BOOL enableReadReceipt __deprecated_msg(
"已废弃,请使用enabledReadReceiptConversationTypeList,设置开启回执的会话类型。");

2. RCMessageCell

@property (nonatomic, strong) UIView *messageHasReadStatusView;

上面接口已废弃删除,可用原有的 statusContentView 替代

3. RCChatSessionInputBarControl

以下代理方法被删除:

- (void)imageDidSelect:(NSArray *)selectedImages fullImageRequired:(BOOL)full __deprecated_msg("已废弃,请勿使用。");

请用以下方法替代

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

另外,RCChatSessionInputBarControl 类里的枚举均迁移到 RCExtensionKitDefine 类中。

4. RCPluginBoardView

插入或者更新扩展面板 button的方法均更改,具体是每个方法增加了一个 highlightedImage 参数,主要是给 PluginBoardItem 增加点击状态的图片

/*!
向扩展功能板中插入扩展项

@param normalImage 扩展项的展示图片
@param highlightedImage 扩展项的触摸高亮图片
@param title 扩展项的展示标题
@param index 需要添加到的索引值
@param tag 扩展项的唯一标示符

@discussion 您以在RCConversationViewController的viewdidload后,添加自定义的扩展项。
SDK默认的扩展项的唯一标示符为1XXX,我们建议您在自定义扩展功能时不要选用1XXX,以免与SDK预留的扩展项唯一标示符重复。
*/
- (void)insertItem:(UIImage *)normalImage highlightedImage:(UIImage *)highlightedImage title:(NSString *)title atIndex:(NSInteger)index tag:(NSInteger)tag;

/*!
添加扩展项到扩展功能板,并在显示为最后一项

@param normalImage 扩展项的展示图片
@param highlightedImage 扩展项的触摸高亮图片
@param title 扩展项的展示标题
@param tag 扩展项的唯一标示符

@discussion 您以在RCConversationViewController的viewdidload后,添加自定义的扩展项。
SDK默认的扩展项的唯一标示符为1XXX,我们建议您在自定义扩展功能时不要选用1XXX,以免与SDK预留的扩展项唯一标示符重复。
*/
- (void)insertItem:(UIImage *)normalImage highlightedImage:(UIImage *)highlightedImage title:(NSString *)title tag:(NSInteger)tag;

/*!
更新指定扩展项

@param index 扩展项的索引值
@param normalImage 扩展项的展示图片
@param highlightedImage 扩展项的触摸高亮图片
@param title 扩展项的展示标题
*/
- (void)updateItemAtIndex:(NSInteger)index normalImage:(UIImage *)normalImage highlightedImage:(UIImage *)highlightedImage title:(NSString *)title;

/*!
更新指定扩展项

@param tag 扩展项的唯一标示符
@param normalImage 扩展项的展示图片
@param highlightedImage 扩展项的触摸高亮图片
@param title 扩展项的展示标题
*/
- (void)updateItemWithTag:(NSInteger)tag normalImage:(UIImage *)normalImage highlightedImage:(UIImage *)highlightedImage title:(NSString *)title;

5. 设置页面类删除

RCSettingViewControllerRCConversationSettingTableViewController会话设置类已移除,如果需要,可以参考官网 SealTalk demo 源码中的 RCDSettingViewController,RCDPrivateSettingsTableViewController 及 RCDGroupSettingsTableViewController 来实现会话设置页

6. RCImagePreviewController

RCImagePreviewController 类(会话页面预览单个图片消息控制器)已移除,可以用 RCImageSlideController 类替代,具体实现参考

RCImageSlideController *imagePreviewVC = [[RCImageSlideController alloc] init];
imagePreviewVC.messageModel = model;
imagePreviewVC.onlyPreviewCurrentMessage = YES;//是否只预览当前图片消息,默认为 NO,支持当前会话图片消息滑动预览,如果设置为 YES, 只预览当前图片消息
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:imagePreviewVC];
nav.modalPresentationStyle = UIModalPresentationFullScreen;
[self presentViewController:nav animated:YES completion:nil];

7. RCKitUtility

RCKitUtility 工具类中下面方法已移除,请使用 RCAlertView 中对应的方法

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

8. 资源图片名称修改

会话页面输入栏加号扩展中的图片命名替换为 plugin_item 为前缀类型的命名;

输入框切换语音输入按钮表情按钮加号按钮的 icon 替换为 inputbar_xxx 类型的命名。

如果开发者之前直接替换过 SDK 上述资源图片,请注意修改对应图片名称

9. 消息气泡拉伸比例修改

原来的拉伸比例:
UIEdgeInsetsMake(image.size.height * 0.8, image.size.width * 0.2, image.size.height * 0.2, image.size.width * 0.8)

修改后的拉伸比例:
UIEdgeInsetsMake(image.size.height * 0.5, image.size.width * 0.5, image.size.height * 0.5, image.size.width * 0.5)

10. 音视频资源图片变更

RongIMKit 中不再包含 RongCallKit 库中所需的图片资源和语言文件,已转移到 RongCallKit 库中

11. 注册自定义消息 cell 时机

如果有自定义消息 Cell,在会话页面 viewDidload 方法中必须优先注册自定义 Cell,再做其他操作