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

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