IMLib 2.X 升级到 5.X

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

接口变更说明

连接接口发生了变更，新版连接接口有如下两个：

连接接口 1

- (void)connectWithToken:(NSString *)token
                dbOpened:(void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(void (^)(NSString *userId))successBlock
                   error:(void (^)(RCConnectErrorCode status))errorBlock

用户调用接口之后，如果因为网络原因暂时连接不上，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

用户调用接口之后，SDK 会在 timeLimit 秒内尝试连接，超过时间将会返回超时并停止连接，timeLimit 小于等于 0 行为和没有 timeLimit 的接口一样。

错误回调处理

新增的连接接口，可自行重连的中间错误码将不再触发 onError 回调（如旧版的 RC_NET_CHANNEL_INVALID 等），只有发生 SDK 无法处理的错误才会触发 onError 回调。

跟旧版的另外一个区别是，onError 回调触发后，4.0.0 将不再重连。而旧版 SDK 在出现可自行重连的中间错误码触发 onError 回调后，还会进行自动重连。

连接错误信息

31004：Token 无效。
处理方案：从 APP 服务器获取新的 token ，再调用 connect 接口进行连接。

31010： 用户被踢下线。
处理法案：退回到登录页面，给用户提示被踢掉线。

31023：用户在其它设备上登录。
处理方案：退回到登录页面，给用户提示其他设备登录了当前账号。

31009：用户被封禁。
处理方案：退回到登录页面，给用户提示被封禁。

34006：自动重连超时(发生在 timeLimit 为有效值并且网络极差的情况下)。
处理方案：重新调用 connect 接口进行连接。

31008：Appkey 被封禁。
处理方案：请检查您使用的 AppKey 是否被封禁或已删除。

33001：SDK 没有初始化。
处理方案：在使用 SDK 任何功能之前，必须先 Init。

33003：开发者接口调用时传入的参数错误。
处理方案：请检查接口调用时传入的参数类型和值。

33002：数据库错误。
处理方案：检查用户 userId 是否包含特殊字符，SDK userId支持大小写英文字母与数字的组合，最大长度 64 字节。

连接错误解决方案

error 回调中判断是否是 token 非法和连接超时。
连接状态回调中判断是否是连接状态是否是 token 非法、踢掉线、封禁、自动重连超时等情况，并按照上述处理方案处理。

//1.连接处理
[[RCIMClient sharedRCIMClient] connectWithToken:newToken
        dbOpened:^(RCDBErrorCode code) {
            //消息数据库打开，可以进入到主页面
        }
        success:^(NSString *userId) {
            //连接成功
        }
        error:^(RCConnectErrorCode status) {
            if (status == RC_CONN_TOKEN_INCORRECT) {
                //从 APP 服务获取新 token，并重连
            } else {
                //无法连接到 IM 服务器，请根据相应的错误码作出对应处理
            }
        }]
//或者
[[RCIMClient sharedRCIMClient] 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 服务器，请根据相应的错误码作出对应处理
        }
    }]

由静态库修改为动态库

5.0.0 相较于旧版本，SDK 从静态库修改为动态库。

5.1.1 动态库改为 XCFramework 形式。 Cocoapod 版本最低为 1.10.0 ，否则可能会无法加载 SDK 或者报 ld: framework not found RandomNames.xcframework

通过手动集成时需要修改:

将原先 IMLib SDK 依赖的系统库全部去掉，如果有 App 或者其他 SDK 依赖的系统库除外
General -> Frameworks,Libraries,and Embedded Binaries 中将 RongXX.framework 的 Embed 由 Do Not Embed 改为 Embed & Sign
引入的 IMLib 的特定头文件如 <RongIMLib/RCUserInfo.h> 修改，请参考常见问题 3。
打包上架时遇到报错 IPA processing failed，请参考常见问题 4。

通过 pod 集成时需要修改

方式一、全量库导入：

pod 'RongCloudIM/IMLib', '5.0.0'            # ChatRoom，Discussion、PublicService、CustomerService、Location、IMLibCore 的合集

方式二、根据需求对 SDK 选择性导入：

pod 'RongCloudIM/IMLibCore', '5.0.0'        # 基础通讯库，必须

pod 'RongCloudIM/ChatRoom', '5.0.0'         # 聊天室，可选
pod 'RongCloudIM/Discussion', '5.0.0'       # 讨论组，可选
pod 'RongCloudIM/PublicService', '5.0.0'    # 公众号，可选
pod 'RongCloudIM/CustomerService', '5.0.0'  # 客服，可选
pod 'RongCloudIM/Location', '5.0.0'         # 实时位置共享，可选

RongIMLib 拆分

为减小 IMLib 本身的尺寸，加载速度，性能等指标，对 RongIMLib 进行了拆分，目前对外提供的 IMLib SDK 有两种：

一种是 RongIMLib，包含了所有功能，接口使用方式不用修改

另外一种是拆分后的 RongIMLibCore（基本通信能力库）、RongCustomerService（客服）、RongPublicService（公众号）、RongDiscussion（讨论组）、RongChatRoom（聊天室）和 RongLocation（实时位置共享），可以根据需求进行选择

// 单例类使用方式需要由原先的 [RCIMClient sharedRCIMClient] 修改为如下：
RongIMLibCore：[RCCoreClient sharedCoreClient]
RongCustomerService：[RCCustomerServiceClient sharedCustomerServiceClient]
RongPublicService：[RCPublicServiceClient sharedPublicServiceClient]
RongDiscussion：[RCDiscussionClient sharedDiscussionClient]
RongChatRoom：[RCChatRoomClient sharedChatRoomClient]
RongLocation：无

旧版本快速兼容方案

说明：以下是旧版本快速兼容方案，但是我们依然建议您参考上面的详细建议进行处理；如果您是直接使用 5.0.0 新版本建议参见上面的详细处理流程。

关键适配点：删除连接接口 token 非法的回调，并将该回调中的处理逻辑，移动至 error 回调中。

[[RCIMClient sharedRCIMClient] connectWithToken:token
            dbOpened:^(RCDBErrorCode code) {
                //如果消息数据库打开，可以进入到主页面
            }
            success:^(NSString *userId) {
                //连接成功
            }
            error:^(RCConnectErrorCode status) {
                if (status == RC_CONN_TOKEN_INCORRECT) {
                    //将旧版本 token 无效的回调处理代码写到这里
                    //从 APP 服务获取新 token，并重连
                } else {
                    //无法连接 im 服务器，请根据相应的错误码作出对应处理
                }
            }];

关键适配点：SDK 引入方式修改。
1. 将原先依赖的系统库全部去掉
2. General -> Frameworks,Libraries,and Embedded Binaries 中将 RongXX.framework 的 Embed 由 Do Not Embed 改为 Embed & Sign

常见问题

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 进行连接。

3. 打包上架时报错：IPA processing failed

建议一：在打包上架时添加删除模拟器架构的脚本

清空项目编译缓存：

选择 Product -> Clean Build Folder，等待清空编译缓存

剔除打包不支持的 x86_64 和 i386 架构：

选择 TARGETS -> Build Phases。
单击加号，选择 New Run Script Phase。

添加如下代码：

# 打包上架时需要添加此脚本

echo "------ extract architectures start ----------------"
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
    FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"

    EXTRACTED_ARCHS=()

    echo "----- FRAMEWORK_EXECUTABLE_NAME = $FRAMEWORK_EXECUTABLE_NAME ARCHS  = $ARCHS -----"

    for ARCH in $ARCHS
    do
        lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
        EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
    done

    lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
    rm "${EXTRACTED_ARCHS[@]}"

    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done

建议二：在打包上架时手动删除模拟器架构

备份 SDK
进入到需要删除模拟器架构的 IMLib.framework 目录中

移除支持 x86_64，i386 的二进制文件

// 此处以 IMLib 举例

// 剔除模拟器架构
lipo RongIMLib.framework/RongIMLib -remove x86_64 -remove i386 -output RongIMLib

// 替换 framwork 内部二进制文件
mv RongIMLib RongIMLib.framework/RongIMLib

// 查看剥离后的二进制文件支持的 CPU 架构，如果显示 armv7 arm64，就可以重新打包了
lipo -info RongIMLib.framework/RongIMLib

4. 如 `<RongIMLib/RCUserInfo.h>` 等这种特定头文件的导入报错

有两种处理方案：

第一、<RongIMLib/RCUserInfo.h> 改成 <RongIMLib/RongIMLib.h>

第二、<RongIMLib/RCUserInfo.h> 改成 <RongIMLibCore/RCUserInfo.h>

被删除的废弃接口说明

IMLib 库 RCIMClient 类以下废弃接口均被删除

SDK 初始化

升级说明: 从 2.4.1 版本开始，为了兼容 Swift 的风格与便于使用，将此方法升级为 initWithAppKey: 方法，方法的功能和使用均不变。
```
- (void)init:(NSString *)appKey __deprecated_msg("已废弃，请勿使用。");
```

获取用户信息

注意：已废弃，请勿使用

//RCIMClient
- (void)getUserInfo:(NSString *)userId
            success:(void (^)(RCUserInfo *userInfo))successBlock
              error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");

插入消息

升级说明：如果您之前使用了此接口，可以直接替换为 insertOutgoingMessage:targetId:sentStatus:content: 接口，行为和实现完全一致。

- (RCMessage *)insertMessage:(RCConversationType)conversationType
                    targetId:(NSString *)targetId
                senderUserId:(NSString *)senderUserId
                  sendStatus:(RCSentStatus)sendStatus
                     content:(RCMessageContent *)content __deprecated_msg("已废弃，请勿使用。");

多媒体消息下载

升级说明：如果您之前使用了此接口，可以直接替换为 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("已废弃，请勿使用。");

多媒体消息下载

升级说明：如果您之前使用了此接口，可以直接替换为 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("已废弃，请勿使用。");

消息发送

升级说明：如果您之前使用了此接口，可以直接替换为 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("已废弃，请勿使用。");

多媒体消息发送

升级说明：如果您之前使用了下面两个接口，可以直接替换为 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("已废弃，请勿使用。");

- (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: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("已废弃，请勿使用。");

全局屏蔽某个时间段的消息提醒

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

- (void)setConversationNotificationQuietHours:(NSString *)startTime
                                     spanMins:(int)spanMins
                                      success:(void (^)(void))successBlock
                                        error:(void (^)(RCErrorCode status))errorBlock
    __deprecated_msg("已废弃，请勿使用。");

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

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

- (void)removeConversationNotificationQuietHours:(void (^)(void))successBlock
                                           error:(void (^)(RCErrorCode status))errorBlock
    __deprecated_msg("已废弃，请勿使用。");

群组相关接口

注意：已废弃，请勿使用

- (void)syncGroups:(NSArray *)groupList
           success:(void (^)(void))successBlock
             error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");

- (void)joinGroup:(NSString *)groupId
        groupName:(NSString *)groupName
          success:(void (^)(void))successBlock
            error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");

- (void)quitGroup:(NSString *)groupId
          success:(void (^)(void))successBlock
            error:(void (^)(RCErrorCode status))errorBlock __deprecated_msg("已废弃，请勿使用。");

评价人工客服

升级说明：如果您之前使用了此接口，可以直接替换为 evaluateCustomerService:dialogId:starValue:suggest:resolveStatus:tagText:extra: 接口，行为和实现完全一致。

- (void)evaluateCustomerService:(NSString *)kefuId
                       dialogId:(NSString *)dialogId
                     humanValue:(int)value
                        suggest:(NSString *)suggest __deprecated_msg("已废弃，请勿使用。");

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

IMLib 2.X 升级到 5.X

接口变更说明​

连接接口 1​

连接接口 2​

错误回调处理​

连接错误信息​

连接错误解决方案​

由静态库修改为动态库​

通过手动集成时需要修改:​

通过 pod 集成时需要修改​

RongIMLib 拆分​

旧版本快速兼容方案​

常见问题​

1. 为什么一部分无法重连错误码的处理逻辑并没有在示例代码中写明？​

2. 旧版本连接过程中一旦出现中间错误码就会立即触发 error 回调，新版本中间错误码不会触发 error 回调了，可能会等很长时间没有任何回调，这要怎么处理？​

3. 打包上架时报错：IPA processing failed​

4. 如 <RongIMLib/RCUserInfo.h> 等这种特定头文件的导入报错​

被删除的废弃接口说明​