全部文档

升级说明 ( 最近更新时间:2020-04-28 19:00:00 )

# iOS 4.0 升级说明

本文会详细描述 4.0.0 版本的修改,如果您只关心升级适配步骤,请参考文末的旧版本快速兼容方案

# 一、接口变更说明

4.0.0 相较于旧版本,只有连接接口发生了变更,新版连接接口如下。

- (void)connectWithToken:(NSString *)token
                dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(void (^)(NSString *userId))successBlock
                   error:(void (^)(RCConnectErrorCode status))errorBlock
已复制
1
2
3
4
- (void)connectWithToken:(NSString *)token
               timeLimit:(int)timeLimit
                dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(void (^)(NSString *userId))successBlock
                   error:(void (^)(RCConnectErrorCode status))errorBlock
已复制
1
2
3
4
5

接口说明:

- (void)connectWithToken:(NSString *)token
                dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(void (^)(NSString *userId))successBlock
                   error:(void (^)(RCConnectErrorCode status))errorBlock
已复制
1
2
3
4

用户调用接口之后,如果因为网络原因暂时连接不上,SDK 会一直尝试重连,直到连接成功或者出现 SDK 无法处理的错误(如 token 非法,用户封禁等)。

- (void)connectWithToken:(NSString *)token
               timeLimit:(int)timeLimit
                dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(void (^)(NSString *userId))successBlock
                   error:(void (^)(RCConnectErrorCode status))errorBlock
已复制
1
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 字节。
已复制
1
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) {
        //用户被封禁,请提示用户并做出对应处理
    }
}
已复制
1
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 服务器,请根据相应的错误码作出对应处理
                }
            }];
已复制
1
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("已废弃,请勿使用。");

已复制
1
2

2.获取用户信息

注意:已废弃,请勿使用

//RCIMClient
- (void)getUserInfo:(NSString *)userId
            success:(void (^)(RCUserInfo *userInfo))successBlock
              error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");

已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
2
3
4
5

10.删除已设置的全局时间段消息提醒屏蔽

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

- (void)removeConversationNotificationQuietHours:(void (^)(void))successBlock
                                           error:(void (^)(RCErrorCode status))errorBlock
    __deprecated_msg("已废弃,请勿使用。");
已复制
1
2
3

11.群组相关接口

注意:已废弃,请勿使用

- (void)syncGroups:(NSArray *)groupList
           success:(void (^)(void))successBlock
             error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃,请勿使用。");
已复制
1
2
3
- (void)joinGroup:(NSString *)groupId
        groupName:(NSString *)groupName
          success:(void (^)(void))successBlock
            error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃,请勿使用。");
已复制
1
2
3
4
- (void)quitGroup:(NSString *)groupId
          success:(void (^)(void))successBlock
            error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃,请勿使用。");
已复制
1
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("已废弃,请勿使用。");
已复制
1
2
3
4
# IMKit 库 RCIM 类以下废弃接口均被删除

1.收到已读回执通知

FOUNDATION_EXPORT NSString *const
    RCKitDispatchReadReceiptNotification __deprecated_msg("已废弃,请使用RCLibDispatchReadReceiptNotification通知。");
已复制
1
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函数。");
已复制
1
2
3
4
5
6
7
8
9

3.开启已读回执功能

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

文档是否解决您的问题 ?

如果遇到产品相关问题,您可 提交工单 寻求帮助