全部文档

更新时间: 2021-03-08

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

# 一、接口变更说明

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

# 连接接口1
connect(final String token, final RongIMClient.ConnectCallback connectCallback)

已复制
1

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

# 连接接口2
connect(final String token, final int timeLimit, final ConnectCallback connectCallback)

已复制
1

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

# 错误回调处理

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

4.0.0 之前的版本为：

public void onError(final RongIMClient.ErrorCode e) 

已复制
1

从 4.0.0 版本开始为：

public void onError(final RongIMClient.ConnectionErrorCode e) 

已复制
1

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.连接处理
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.CONN_USER_BLOCKED)) {
        //用户被封禁，请提示用户并做出对应处理
    }
}

已复制
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
45
46
47
48
49
50
51
52
53
54
55
56
57

# 三、旧版本快速兼容方案

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

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

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

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

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 e) {
            if(e.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_INCORRECT)) {
                //将旧版本 token 无效的回调处理代码写到这里
                //从 APP 服务获取新 token，并重连                  
            }else {
                //无法连接 im 服务器，请根据相应的错误码作出对应处理
            }
        }
});

已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 四、常见问题

# 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 库 RongIMClient 类以下废弃接口均被删除

1.设置是否使用多 CMP 并行链接策略。

升级说明：已删除此接口，无替代方法

public static void setUserPolicy(boolean enable) {"已废弃，请勿使用。"};

已复制
1

2.获取当前用户的本地会话列表

升级说明：如果您之前使用了此接口，可以直接替换为 getConversationList(ResultCallback) 接口，异步获取会话数据。

public List<Conversation> getConversationList(){"已废弃，请勿使用。"};


已复制
1
2

3.获取当前用户的本地会话列表

升级说明：如果您之前使用了此接口，可以直接替换为 getConversationList(ResultCallback) 接口，异步获取会话数据。

public List<Conversation> getConversationList(Conversation.ConversationType... types) {"已废弃，请勿使用。"};


已复制
1
2

4.获取单个会话信息

升级说明：如果您之前使用了此接口，可以直接替换为

getConversation(final Conversation.ConversationType conversationType, final String targetId, final ResultCallback<Conversation> callback)

public Conversation getConversation(Conversation.ConversationType conversationType, String targetId){"已废弃，请勿使用。"};


已复制
1
2

5.从会话列表中移除某一会话

升级说明：如果您之前使用了此接口，可以直接替换为 removeConversation(final Conversation.ConversationType conversationType, final String targetId, final ResultCallback<Boolean> callback)

public boolean removeConversation(Conversation.ConversationType conversationType, String targetId){"已废弃，请勿使用。"};


已复制
1
2

6.设置会话的置顶状态

升级说明：如果您之前使用了此接口，可以直接替换为 setConversationToTop(final Conversation.ConversationType conversationType, final String id, final boolean isTop, final ResultCallback<Boolean> callback)

public boolean setConversationToTop(Conversation.ConversationType conversationType, String targetId, boolean isTop){"已废弃，请勿使用。"};


已复制
1
2

7.获取所有会话的总未读消息数

升级说明：如果您之前使用了此接口，可以直接替换为 getTotalUnreadCount(final ResultCallback<Integer> callback)

public int getTotalUnreadCount(){"已废弃，请勿使用。"};


已复制
1
2

8.获取某会话的未读消息数

升级说明：如果您之前使用了此接口，可以直接替换为 getUnreadCount(Conversation.ConversationType, String, ResultCallback)

public int getTotalUnreadCount(){"已废弃，请勿使用。"};


已复制
1
2

8.获取某几种会话类型的未读消息数

升级说明：如果您之前使用了此接口，可以直接替换为 getUnreadCount(final Conversation.ConversationType[] conversationTypes, final ResultCallback<Integer> callback)

public int getUnreadCount(Conversation.ConversationType... conversationTypes){"已废弃，请勿使用。"};


已复制
1
2

9.获取指定会话的最新消息

升级说明：如果您之前使用了此接口，可以直接替换为 getLatestMessages(Conversation.ConversationType, String, int, ResultCallback)

public List<Message> getLatestMessages(Conversation.ConversationType conversationType, String targetId, int count){"已废弃，请勿使用。"};


已复制
1
2

10.获取会话中符合条件的消息列表

升级说明：如果您之前使用了此接口，可以直接替换为 getHistoryMessages(Conversation.ConversationType, String, int, int, ResultCallback)

public List<Message> getHistoryMessagesByMessageId(Conversation.ConversationType conversationType, String targetId, int oldestMessageId, int count) {"已废弃，请勿使用。"};


已复制
1
2

11.获取会话中符合条件的消息列表

升级说明：如果您之前使用了此接口，可以直接替换为 getHistoryMessagesByObjectNamesSync(final Conversation.ConversationType conversationType, final String targetId,List<String> objectNames, final long timestamp, final int count, final RongCommonDefine.GetMessageDirection direction)

public List<Message> getHistoryMessagesByObjectNames(final Conversation.ConversationType conversationType, final String targetId,final List<String> objectNames, final long timestamp, final int count,final RongCommonDefine.GetMessageDirection direction) {"已废弃，请勿使用。"};


已复制
1
2

12.获取用户在线状态

升级说明：已删除，没有替代方法

public void getUserOnlineStatus(final String userId, final IRongCallback.IGetUserOnlineStatusCallback callback) {
{"已废弃，请勿使用。"};


已复制
1
2
3

13.订阅用户在线状态列表

升级说明：已删除，没有替代方法

public void subscribeUserOnlineStatus(final List<String> userIdList) {"已废弃，请勿使用。"};


已复制
1
2

14.设置用户在线状态监听接口

升级说明：已删除，没有替代方法

public void setSubscribeStatusListener(final IRongCallback.ISetSubscribeStatusCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

15.设置当前用户在线状态

升级说明：已删除，没有替代方法

public void setUserOnlineStatus(final int status, final IRongCallback.ISetUserOnlineStatusCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

16.获取会话中，从指定消息之前、指定数量的、指定消息类型的最新消息实体

升级说明：已删除，没有替代方法

public void getHistoryMessagesOneWay(final Conversation.ConversationType conversationType, final String targetId, final int oldestMessageId, final int count, final ResultCallback<List<Message>> callback) {"已废弃，请勿使用。"};


已复制
1
2

17.删除消息

升级说明：如果您之前使用了此接口，可以直接替换为 deleteMessages(int[], ResultCallback)

public boolean deleteMessages(int[] messageIds) {"已废弃，请勿使用。"};


已复制
1
2

18.删除某个会话中的所有消息

升级说明：如果您之前使用了此接口，可以直接替换为 clearMessages(Conversation.ConversationType, String, ResultCallback)

public boolean clearMessages(Conversation.ConversationType conversationType, String targetId) {"已废弃，请勿使用。"};


已复制
1
2

19.清除某个会话中的未读消息数

升级说明：如果您之前使用了此接口，可以直接替换为 clearMessagesUnreadStatus(Conversation.ConversationType, String, ResultCallback)

public boolean clearMessagesUnreadStatus(Conversation.ConversationType conversationType, String targetId) {"已废弃，请勿使用。"};


已复制
1
2

20.设置本地消息的附加信息

升级说明：如果您之前使用了此接口，可以直接替换为 setMessageExtra(int, String, ResultCallback)

public boolean setMessageExtra(int messageId, String value) {"已废弃，请勿使用。"};


已复制
1
2

21.设置消息的接收状态

升级说明：如果您之前使用了此接口，可以直接替换为 setMessageReceivedStatus(int, Message.ReceivedStatus, ResultCallback)

public boolean setMessageReceivedStatus(int messageId, Message.ReceivedStatus receivedStatus) {"已废弃，请勿使用。"};


已复制
1
2

22.设置消息发送状态

升级说明：如果您之前使用了此接口，可以直接替换为 setMessageSentStatus(Message, ResultCallback)

public boolean setMessageSentStatus(int messageId, Message.SentStatus sentStatus) {"已废弃，请勿使用。"};


已复制
1
2

23.设置消息发送状态

升级说明：如果您之前使用了此接口，可以直接替换为 setMessageSentStatus(Message, ResultCallback)

public void setMessageSentStatus(final int messageId, final Message.SentStatus sentStatus, final ResultCallback<Boolean> callback) {"已废弃，请勿使用。"};


已复制
1
2

24.获取会话中的草稿信息

升级说明：如果您之前使用了此接口，可以直接替换为 getTextMessageDraft(Conversation.ConversationType, String, ResultCallback)

public String getTextMessageDraft(final Conversation.ConversationType conversationType, final String targetId) {"已废弃，请勿使用。"};


已复制
1
2

25.保存会话草稿信息

升级说明：如果您之前使用了此接口，可以直接替换为 saveTextMessageDraft(Conversation.ConversationType, String, String, ResultCallback)

public boolean saveTextMessageDraft(Conversation.ConversationType conversationType, String targetId, final String content) {"已废弃，请勿使用。"};


已复制
1
2

26.删除指定会话中的草稿信息

升级说明：如果您之前使用了此接口，可以直接替换为 clearTextMessageDraft(Conversation.ConversationType, String, ResultCallback)

public boolean clearTextMessageDraft(Conversation.ConversationType conversationType, String targetId) {"已废弃，请勿使用。"};


已复制
1
2

27.向本地会话中插入一条消息

升级说明：如果您之前使用了此接口，可以直接替换为 insertIncomingMessage(Conversation.ConversationType, String, String, Message.ReceivedStatus, MessageContent, long, ResultCallback) 或者 insertOutgoingMessage(Conversation.ConversationType, String, Message.SentStatus, MessageContent, long, ResultCallback)

public void insertMessage(final Conversation.ConversationType type, final String targetId, final String senderUserId, final MessageContent content, final long sentTime, final ResultCallback<Message> resultCallback) {"已废弃，请勿使用。"};


已复制
1
2

28.向本地会话中插入一条消息

升级说明：如果您之前使用了此接口，可以直接替换为 insertIncomingMessage(Conversation.ConversationType, String, String, Message.ReceivedStatus, MessageContent, long, ResultCallback) 或者 insertOutgoingMessage(Conversation.ConversationType, String, Message.SentStatus, MessageContent, long, ResultCallback)

public void insertMessage(final Conversation.ConversationType conversationType, final String targetId, final String senderUserId, final MessageContent content, final ResultCallback<Message> resultCallback) {"已废弃，请勿使用。"};


已复制
1
2

29.发送消息

升级说明：如果您之前使用了此接口，可以直接替换为 sendMessage(Conversation.ConversationType, String, MessageContent, String, String, IRongCallback.ISendMessageCallback)

public Message sendMessage(final Conversation.ConversationType type, final String targetId, final MessageContent content, final String pushContent, final String pushData, final SendMessageCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

30.根据会话类型，发送消息

升级说明：如果您之前使用了此接口，可以直接替换为 sendMessage(Conversation.ConversationType, String, MessageContent, String, String, IRongCallback.ISendMessageCallback)

public void sendMessage(final Conversation.ConversationType conversationType, final String targetId, final MessageContent content, final String pushContent, final String pushData, final SendMessageCallback callback, final ResultCallback<Message> resultCallback) {"已废弃，请勿使用。"};


已复制
1
2

31.发送消息

升级说明：如果您之前使用了此接口，可以直接替换为 sendMessage(Message, String, String, IRongCallback.ISendMessageCallback)

public void sendMessage(final Message message, final String pushContent, final String pushData, final SendMessageCallback callback, final ResultCallback<Message> resultCallback) {"已废弃，请勿使用。"};


已复制
1
2

32.发送消息，返回发送的消息实体

升级说明：如果您之前使用了此接口，可以直接替换为 sendMessage(Message, String, String, IRongCallback.ISendMessageCallback)

public Message sendMessage(final Message message, final String pushContent, final String pushData, final SendMessageCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

32.同步当前用户所在的群组列表信息

升级说明：已废弃，建议您通过您的 App Server进行群组操作

public void syncGroup(final List<Group> groups, final OperationCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

33.加入群组

升级说明：不建议在端上使用，而是通过服务器调用 server api 加入群组

public void joinGroup(final String groupId, final String groupName, final OperationCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

34.退出群组

升级说明：不建议在端上使用，而是通过服务器调用 server api 退出群组

public void quitGroup(final String groupId, final OperationCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

34.清空指定会话类型列表中的所有会话及会话信息

升级说明：如果您之前使用了此接口，可以直接替换为 clearConversations(ResultCallback, Conversation.ConversationType...)

public boolean clearConversations(Conversation.ConversationType... conversationTypes) {"已废弃，请勿使用。"};


已复制
1
2

35.同步用户信息

升级说明：已删除，无替代方法

public void syncUserData(final UserData userData, final OperationCallback callback) {"已废弃，请勿使用。"};


已复制
1
2

36.更新位置共享坐标位置

升级说明：已删除，无替代方法

public void updateRealTimeLocationStatus(Conversation.ConversationType conversationType, String targetId, double latitude, double longitude) {"已废弃，请勿使用。"};


已复制
1
2

37.撤回消息监听器

升级说明：已删除，无替代方法

public interface RecallMessageListener {"已废弃，请勿使用。"};


已复制
1
2

38.设置撤回消息监听器

升级说明：已删除，无替代方法

public static void setRecallMessageListener(final RecallMessageListener listener) {"已废弃，请勿使用。"};


已复制
1
2

39.设置推送相关配置信息改变的监听

升级说明：已删除，无替代方法

public void setPushNotificationListener(final PushNotificationListener listener) {"已废弃，请勿使用。"};


已复制
1
2

40.设置本地数据库的会话消息提醒状态

升级说明：已删除，使用设置服务器会话消息提醒状态接口

public void syncConversationNotificationStatus(final Conversation.ConversationType conversationType, final String targetId, final Conversation.ConversationNotificationStatus notificationStatus, final RongIMClient.ResultCallback<Boolean> callback) {"已废弃，请勿使用。"};


已复制
1
2
# IMKit 库 RCIM 类以下废弃接口均被删除

说明：RongIM 封装了 RongIMClient 的方法所以 lib 中删除的废弃方法，对应 IM 的方法也被删除，方法明和使用方法都一样

1.RongIMClientWrapper 类

升级说明：已删除，不在使用此类

public RongIMClientWrapper getRongIMClient() {"已废弃“};


已复制
1
2

文档是否解决您的问题 ?

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