更新时间: 2021-03-08
本文会详细描述 4.0.0 版本相对于 2.X 的修改，如果您只关心升级适配步骤，请参考文末的旧版本快速兼容方案。
# 一、接口变更说明
4.0.0 相较于旧版本，只有连接接口发生了变更，新版连接接口有如下两个：
# 连接接口1
- (void)connectWithToken:(NSString *)token dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock success:(void (^)(NSString *userId))successBlock error:(void (^)(RCConnectErrorCode status))errorBlock已复制
2
3
4
用户调用接口之后，如果因为网络原因暂时连接不上，SDK 会一直尝试重连，直到连接成功或者出现 SDK 无法处理的错误（如 token 非法，用户封禁等）。
# 连接接口2
- (void)connectWithToken:(NSString *)token timeLimit:(int)timeLimit dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock success:(void (^)(NSString *userId))successBlock error:(void (^)(RCConnectErrorCode status))errorBlock已复制
2
3
4
5
用户调用接口之后，SDK 会在 timeLimit 秒内尝试连接，超过时间将会返回超时并停止连接，timeLimit <= 0 行为和没有 timeLimit 的接口一样。
# 错误回调处理
4.0.0 的连接接口，可自行重连的中间错误码将不再触发 onError 回调（如旧版的 RC_NET_CHANNEL_INVALID 等），只有发生 SDK 无法处理的错误才会触发 onError 回调。
跟旧版的另外一个区别是，onError 回调触发后，4.0.0 将不再重连。而旧版 SDK 在出现可自行重连的中间错误码触发 onError 回调后，还会进行自动重连。
# 连接错误信息
31004：Token 无效。 处理方案：从 APP 服务器获取新的 token ，再调用 connect 接口进行连接。 31010： 用户被踢下线。 处理法案：退回到登录页面，给用户提示被踢掉线。 31023：用户在其它设备上登录。 处理方案：退回到登录页面，给用户提示其他设备登录了当前账号。 31011：用户被封禁。 处理方案：退回到登录页面，给用户提示被封禁。 34006：自动重连超时(发生在 timeLimit 为有效值并且网络极差的情况下)。 处理方案：重新调用 connect 接口进行连接。 31008：Appkey 被封禁。 处理方案：请检查您使用的 AppKey 是否被封禁或已删除。 33001：SDK 没有初始化。 处理方案：在使用 SDK 任何功能之前，必须先 Init。 33003：开发者接口调用时传入的参数错误。 处理方案：请检查接口调用时传入的参数类型和值。 33002：数据库错误。 处理方案：检查用户 userId 是否包含特殊字符，SDK userId 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 64 字节。已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 连接错误解决方案
或者直接参考
二、示例代码。
1.error 回调中判断是否是 token 非法和连接超时超时。
2.连接状态回调中判断是否是连接状态是否是 token 非法、踢掉线、封禁、自动重连超时 等情况，并按照上述处理方案处理。
# 二、示例代码
注：示例代码按照 IMKit 的相关接口进行演示，如果您使用 IMLib，SDK 的业务处理逻辑是一致的，根据 IMLib 的相关接口进行接口替换即可。
//1.连接处理 [[RCIM sharedRCIM] connectWithToken:newToken dbOpened:^(RCDBErrorCode code) { //消息数据库打开，可以进入到主页面 } success:^(NSString *userId) { //连接成功 } error:^(RCConnectErrorCode status) { if (status == RC_CONN_TOKEN_INCORRECT) { //从 APP 服务获取新 token，并重连 } else { //无法连接到 IM 服务器，请根据相应的错误码作出对应处理 } }] //或者 [[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] setConnectionStatusDelegate:self]; - (void)onRCIMConnectionStatusChanged:(RCConnectionStatus)status { if (status == ConnectionStatus_KICKED_OFFLINE_BY_OTHER_CLIENT) { //当前用户账号在其他端登录，请提示用户并做出对应处理 } else if (status == ConnectionStatus_DISCONN_EXCEPTION) { //用户被封禁，请提示用户并做出对应处理 } }已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# 三、旧版本快速兼容方案
说明：以下是旧版本快速兼容方案，但是我们依然建议您参考上面的详细建议进行处理；如果您是直接使用 4.0.0 新版本建议参见上面的详细处理流程。
::: 关键适配点：删除连接接口 token 非法的回调，并将该回调中的处理逻辑，移动至 error 回调中。:::
以下代码以 IMKit 为例，IMLib 修改对应的核心类即可(注意代码注释)。
[[RCIM sharedRCIM] connectWithToken:token dbOpened:^(RCDBErrorCode code) { //如果消息数据库打开，可以进入到主页面 } success:^(NSString *userId) { //连接成功 } error:^(RCConnectErrorCode status) { if (status == RC_CONN_TOKEN_INCORRECT) { //将旧版本 token 无效的回调处理代码写到这里 //从 APP 服务获取新 token，并重连 } else { //无法连接 im 服务器，请根据相应的错误码作出对应处理 } }];已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 四、常见问题
# 1.为什么一部分无法重连错误码的处理逻辑并没有在示例代码中写明？
都是开发阶段的问题，不需要代码兼容处理。
31008： Appkey 被封禁
当发生这个问题的时候，您可以自行在融云开发者后台查看您的 appkey 使用状态，大多情况是 appkey 被自行删除或者欠费。
33001：SDK 没有初始化
这个错误只会发生在开发阶段，只要您保证先 init 后 connect 就不会有这个问题。
33003：开发者接口调用时传入的参数错误
这个错误只会发生在开发阶段，很可能是传入的 token 为空，只要保证 connect 传入正确合法的 token 就不会有这个问题。
33002：数据库错误
这个问题只会发生在开发阶段，很可能是您的用户 id 体系和我们 SDK 的不一致，一般该情况很少发生。
# 2.旧版本连接过程中一旦出现中间错误码就会立即触发 error 回调，新版本中间错误码不会触发 error 回调了，可能会等很长时间没有任何回调，这要怎么处理？
以下的建议，择一选取即可。
建议1.
用户第一次登录，设置 timeLimit 为有效值，网络极差情况下超时回调 error。
用户后续登录，调用没有 timeLimit 的接口，SDK 就会保持旧版本的自动重连。
建议2.
设置 SDK 的连接状态监听，APP 自行做超时的记录，如果超时了，APP 可以自动断开连接再调用 connect 进行连接。
# 五、被删除的废弃接口说明
# IMLib 库 RCIMClient 类以下废弃接口均被删除
1.SDK 初始化
升级说明: 从 2.4.1 版本开始，为了兼容 Swift 的风格与便于使用，将此方法升级为 initWithAppKey:
方法，方法的功能和使用均不变。
- (void)init:(NSString *)appKey __deprecated_msg("已废弃，请勿使用。");已复制
2
2.获取用户信息
注意：已废弃，请勿使用
//RCIMClient - (void)getUserInfo:(NSString *)userId success:(void (^)(RCUserInfo *userInfo))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
3.插入消息
升级说明：如果您之前使用了此接口，可以直接替换为
insertOutgoingMessage:targetId:sentStatus:content: 接口，行为和实现完全一致。
- (RCMessage *)insertMessage:(RCConversationType)conversationType targetId:(NSString *)targetId senderUserId:(NSString *)senderUserId sendStatus:(RCSentStatus)sendStatus content:(RCMessageContent *)content __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
6
4.多媒体消息下载
升级说明：如果您之前使用了此接口，可以直接替换为 downloadMediaFile:mediaUrl:progress:success:error:cancel: 接口
行为和实现完全一致。
- (void)downloadMediaFile:(NSString *)fileName mediaUrl:(NSString *)mediaUrl progress:(void (^)(int progress))progressBlock success:(void (^)(NSString *mediaPath))successBlock error:(void (^)(RCErrorCode errorCode))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
5.多媒体消息下载
升级说明：如果您之前使用了此接口，可以直接替换为 downloadMediaFile:targetId:mediaType:mediaUrl:progress:success:error:cancel: 接口
行为和实现完全一致。
- (void)downloadMediaFile:(RCConversationType)conversationType targetId:(NSString *)targetId mediaType:(RCMediaType)mediaType mediaUrl:(NSString *)mediaUrl progress:(void (^)(int progress))progressBlock success:(void (^)(NSString *mediaPath))successBlock error:(void (^)(RCErrorCode errorCode))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
6
7
6.消息发送
升级说明：如果您之前使用了此接口，可以直接替换为
sendMessage:targetId:content:pushContent:pushData:success:error: 接口（pushData传为 nil），行为和实现完全一致。
- (RCMessage *)sendMessage:(RCConversationType)conversationType targetId:(NSString *)targetId content:(RCMessageContent *)content pushContent:(NSString *)pushContent success:(void (^)(long messageId))successBlock error:(void (^)(RCErrorCode nErrorCode, long messageId))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
6
7
7.多媒体消息发送
升级说明：如果您之前使用了下面两个接口，可以直接替换为
sendMediaMessage:targetId:content:pushContent:pushData:progress:success:error:cancel: 接口（pushData传为nil），行为和实现完全一致。
- (RCMessage *)sendImageMessage:(RCConversationType)conversationType targetId:(NSString *)targetId content:(RCMessageContent *)content pushContent:(NSString *)pushContent progress:(void (^)(int progress, long messageId))progressBlock success:(void (^)(long messageId))successBlock error:(void (^)(RCErrorCode errorCode, long messageId))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
6
7
8
- (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("已废弃，请勿使用。");已复制
2
3
4
5
6
7
8
9
8.上传图片到指定的服务器的消息发送接口
升级说明：如果您之前使用了此接口，可以直接替换为
sendMediaMessage:targetId:content:pushContent:pushData:uploadPrepare:progress:success:error:cancel: 接口，行为和实现完全一致。
- (RCMessage *)sendImageMessage:(RCConversationType)conversationType targetId:(NSString *)targetId content:(RCMessageContent *)content pushContent:(NSString *)pushContent pushData:(NSString *)pushData uploadPrepare:(void (^)(RCUploadImageStatusListener *uploadListener))uploadPrepareBlock progress:(void (^)(int progress, long messageId))progressBlock success:(void (^)(long messageId))successBlock error:(void (^)(RCErrorCode errorCode, long messageId))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
6
7
8
9
10
9.全局屏蔽某个时间段的消息提醒
升级说明：如果您之前使用了此接口，可以直接替换为
setNotificationQuietHours:spanMins:success:error: 接口，行为和实现完全一致。
- (void)setConversationNotificationQuietHours:(NSString *)startTime spanMins:(int)spanMins success:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
5
10.删除已设置的全局时间段消息提醒屏蔽
升级说明：如果您之前使用了此接口，可以直接替换为 removeNotificationQuietHours:error: 接口，行为和实现完全一致。
- (void)removeConversationNotificationQuietHours:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
11.群组相关接口
注意：已废弃，请勿使用
- (void)syncGroups:(NSArray *)groupList success:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
- (void)joinGroup:(NSString *)groupId groupName:(NSString *)groupName success:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
- (void)quitGroup:(NSString *)groupId success:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");已复制
2
3
12.评价人工客服
升级说明：如果您之前使用了此接口，可以直接替换为
evaluateCustomerService:dialogId:starValue:suggest:resolveStatus:tagText:extra:
接口，行为和实现完全一致。
- (void)evaluateCustomerService:(NSString *)kefuId dialogId:(NSString *)dialogId humanValue:(int)value suggest:(NSString *)suggest __deprecated_msg("已废弃，请勿使用。");已复制
2
3
4
# IMKit 库 RCIM 类以下废弃接口均被删除
1.收到已读回执通知
FOUNDATION_EXPORT NSString *const RCKitDispatchReadReceiptNotification __deprecated_msg("已废弃，请使用RCLibDispatchReadReceiptNotification通知。");已复制
2
2.图片消息发送
升级说明：如果您之前使用了此接口，可以直接替换为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函数。");已复制
2
3
4
5
6
7
8
9
3.开启已读回执功能
@property (nonatomic, assign) BOOL enableReadReceipt __deprecated_msg( "已废弃，请使用enabledReadReceiptConversationTypeList，设置开启回执的会话类型。");已复制
2