当前知识库站点已不再维护。请移步新版知识库：https://help.rongcloud.cn/
  1. 知识库
  2.  / IM 即时通讯
  3.  / Android
  4.  / 初始化&链接

IM SDK 2.x --> 4.x 升级兼容文档

IM sdk 2.x版本升级到4.x版本的适配文档.
发布时间： 2020-06-22 18:41

回答：

融云 IM SDK 4.0.0 兼容文档

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

一、接口变更说明

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

iOS

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

Android

connect(final String token, final RongIMClient.ConnectCallback connectCallback)
connect(final String token, final int timeLimit, final ConnectCallback connectCallback)

其中 RongIMClient.ConnectCallback 中的 onError 回调参数发生了改变。

4.0.0 之前的版本为：

 public void onError(final RongIMClient.ErrorCode e)

从 4.0.0 版本开始为：

public void onError(final RongIMClient.ConnectionErrorCode e)

接口说明:

iOS

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

Android

connect(final String token, final RongIMClient.ConnectCallback connectCallback)

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

iOS

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

Android

connect(final String token, final int timeLimit, final ConnectCallback connectCallback)

用户调用接口之后，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.error 回调中判断是否是 token 非法和连接超时超时。

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

二、示例代码

注：示例代码按照 IMKit 的相关接口进行演示，如果您使用 IMLib，SDK 的业务处理逻辑是一致的，根据 IMLib 的相关接口进行接口替换即可。

iOS

//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_TOKEN_INCORRECT) {
        //Token 非法，从 APP 服务获取新 token，并重连
    } else if (status == ConnectionStatus_DISCONN_EXCEPTION) {
        //用户被封禁，请提示用户并做出对应处理
    }
}

Android

//1.连接处理
RongIM.connect(token, new RongIMClient.ConnectCallback() {
    @Override
    public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
        //消息数据库打开，可以进入到主页面
    }

    @Override
    public void onSuccess(String s) {
        //连接成功
    }

    @Override
    public void onError(RongIMClient.ConnectionErrorCode errorCode) {
        if(errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_INCORRECT)) {
            //从 APP 服务获取新 token，并重连
        }else {
            //无法连接到 IM 服务器，请根据相应的错误码作出对应处理
        }
    }
})
//或者
RongIM.connect(token,5, new RongIMClient.ConnectCallback() {
    @Override
    public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
        //消息数据库打开，可以进入到主页面
    }

    @Override
    public void onSuccess(String s) {
        //连接成功
    }

    @Override
    public void onError(RongIMClient.ConnectionErrorCode errorCode) {
        if(errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_INCORRECT)) {
            //从 APP 服务获取新 token，并重连
        } else if (errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONNECT_TIMEOUT)) {
            //连接超时，弹出提示，可以引导用户等待网络正常的时候再次点击进行连接
        } else {
            //无法连接 IM 服务器，请根据相应的错误码作出对应处理
        }
    }
})

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

//其中 this 最好为单例类，以此保证在整个 APP 生命周期，该类都能够检测到 SDK 连接状态的变更
RongIM.setConnectionStatusListener(this);

public void onChanged(ConnectionStatus connectionStatus) {
    if (connectionStatus.equals(ConnectionStatus.KICKED_OFFLINE_BY_OTHER_CLIENT)) {
        //当前用户账号在其他端登录，请提示用户并做出对应处理
    } else if (connectionStatus.equals(ConnectionStatus.TOKEN_INCORRECT)) {
        //token 非法，从 APP 服务获取新 token，并重连
    } else if (connectionStatus.equals(ConnectionStatus.CONN_USER_BLOCKED)) {
        //用户被封禁，请提示用户并做出对应处理
    }
}

三、旧版本快速兼容方案

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

关键适配点：

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

Android 修改连接接口 onError 回调的参数类型，由 RongIMClient.ErrorCode 改为 RongIMClient.ConnectionErrorCode。

示例代码

以下代码以 IMKit 为例，IMLib 修改对应的核心类即可。

iOS

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

Android

RongIM.connect(token, new RongIMClient.ConnectCallback() {
        @Override
        public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
            //如果消息数据库打开，可以进入到主页面
        }

        @Override
        public void onSuccess(String s) {
            //连接成功
        }

        @Override
        public void onError(RongIMClient.ErrorCode e) {
            if(e.equals(RongIMClient.ErrorCode.RC_CONN_USER_OR_PASSWD_ERROR)) {
                //将旧版本 token 非法的回调处理代码写到这里
                //从 APP 服务获取新 token，并重连                  
            }else {
                //无法连接 im 服务器，请根据相应的错误码作出对应处理
            }
        }
});

四、常见问题

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

其他相关问题：