SDK 2.x 至 3.0 升级指南


使用升级替换脚本

可以使用 SDK 中的自动替换脚本替换大部分原有 API 的变动,有部分需要手动更新的请见下面的说明。

./replace.sh your_source_folder

注意:

  • 该脚本可以允许在 Linux、Mac 及 Cygwin 环境下并需要可执行权限;
  • 如果在 Mac 下,需要用户用 brew 或其他方式安装 gsed。

API 大致变动介绍

3.0 中的核心类为 EMClient 类,通过 emclient 类可以获取到 chatmanager、groupmanager、contactmanager、chatroommanager 等 manager 对象,此外和这些 manager 不太相关的方法基本 EMClient 类里面,如登录、设置连接监听等方法。message 里的成员变量的获取都变成 getXXX 获取。

从 2.x 升级到 3.0,大部分的变动只需要改变 API 名称就可以了,但是少部分地方因为架构等原因需要一些稍复杂的改动。

这里先列出API大概的变动列表:

SDK2.x SDK3.0
登录初始化相关
EMChat EMClient,emchat里之前的方法基本都在此类里
EMChatManager、EMGroupManger等manager类 都通过EMClient类获取,如:EMClient.getInstance().chatManager()
EMChat.getInstance().init(context); EMClient.getInstance().init(appContext, options); options需要初始化的适合一并传入
EMChatOptions,通过chatmanager获取到任何直接设置其值 EMOptions,通过new创建得到,设置其成员的值后,调用init方法时传入此options
options.setUseRoster() 无,登录的时候SDK默认不会获取好友
Chatmanager里的setGCMProjectNumber方法移到EMClient里 EMClient.getInstance().setGCMProjectNumber(projectNumber);同理,设置第三方推送配置的方法也在此类里
EMChat.getInstance().setAutoLogin(false) 初始化通过option.setAutoLogin(false)设置
EMChat.getInstance().isLoggedIn() EMClient.getInstance().isLoggedInBefore()
EMChatManager.getInstance().logout() EMClient.getInstance().logout()
EMChatmanager.getInstance().createAccountOnServer() EMClient.getInstance().createAccount()
连接状态相关
EMChatManager.getInstance(). addConnectionListener(connectionListener) EMClient.getInstance().addConnectionListener(connectionListener);同理unregister方法调用removeConnectionListener
EMChatManager.getInstance().isConnected() EMClient.getInstance().isConnected()
消息相关
EMMessage 之前的public的成员变量都只能通过getXxx()的方式获取
MessageBody: TextMessageBody、VideoMessageBody等 都需要在前面加上EM,如:TextMessageBody->EMTextMessageBody
EMEventListener EMMessageListener,需要注意的是,3.0 的消息没有离线消息的回调,不区分离线消息和在线消息
EMChatManager.getInstance().registerEventListener EMClient.getInstance().chatManager().addMessageListener,移除监听调用removeMessageListener
conversation.getMsgCount() 无,使用conversation.getAllMessages().size取到count
conversation.loadMoreGroupMsgFromDB() 无,都使用conversation.loadMoreMsgFromDB()
EMChatmanager.getInstance().sendMessage(msg, callback) 无callback,通过message.setMessageStatusCallback(EMCallBack callback)获取消息发送状态
conversation.addMessage(message) 无此方法,发送消息之前无需调用此方法
conversation.getMessage(Pos); 无,重发消息的时候需要传message对象作为intent的参数
EMChatmanager.getInstance().asyncFetchMessage() 语音消息调用EMClient.getInstance().chatManager().downloadAttachment();图片、视频消息等自动下载缩略图的消息调用downloadThumbnail()方法
EMChatManager.getInstance().clearConversation 无,使用EMClient.getInstance().deleteConversation方法即可
EMChatManager.getInstance().deleteAllConversation(); 无,for循环调用删除会话方法即可
群组聊天室相关
EMGroup不再继承自EMContact -
创建群组 EMClient.getInstance().groupManager().createGroup(groupName, desc, allMembers, reason, option); 具体参数的意思请参考群组管理文档
EMGroupManager.getInstance(). createOrUpdateLocalGroup(group); 无,调用getGroupFromServer方法时,会自动更新本地有记录的群组
EMGroupManager.getInstance().getGroupsFromServer() EMClient.getInstance().groupManager().getJoinedGroupsFromServer()
EMGroupManager.getInstance().exitFromGroup() EMClient.getInstance().groupManager().leaveGroup()
EMGroupManager.getInstance().exitAndDeleteGroup() EMClient.getInstance().groupManager().destroyGroup()
Chatroom相关的api 都移到EMChatRoomManager类,chatroommanager的实例获取方法为EMClient.getInstance().chatroomManager()
用户相关
EMContact::setUsername() 无,需要在new出emcontact对象时传入username
getCurrentUser()移到EMClient类里 EMClient.getInstance().getCurrentUser()
EMChatmanager.getInstance().updateCurrentUserNick() EMClient.getInstance().updateCurrentUserNick()
EMContactManager.getInstance().getContactUserNames() EMClient.getInstance().contactManager().getAllContactsFromServer()
EMContactManager.getInstance(). getBlackListUsernamesFromServer() EMClient.getInstance().contactManager().getBlackListFromServer()
EMContactManager.getInstance().deleteUserFromBlackList() EMClient.getInstance().contactManager().removeUserFromBlackList()

消息接发对于以前通过 conversation.addConversation() 方法,然后在 adapter 中发送消息的开发者来说变动稍微有点大,这里再单独列出来修改方法:

首先把 conversation.addMessage(message) 删除掉,然后调用 sendmessage 方法,在 messageadapter 显示消息的地方,不再调用 sendmessage 方法,adapter 里只是根据消息的状态显示相应的 UI 即可,通过调用 message.setMessageStatusCallback(messageReceiveCallback),监听消息是否发送成功等,这里以发送文字消息作为示例:

protected void sendMessage(EMMessage message){
        if(chatFragmentListener != null){
            //设置扩展属性
            chatFragmentListener.onSetMessageAttributes(message);
        }
        // 如果是群聊,设置chattype,默认是单聊
        if (chatType == EaseConstant.CHATTYPE_GROUP){
            message.setChatType(ChatType.GroupChat);
        }else if(chatType == EaseConstant.CHATTYPE_CHATROOM){
            message.setChatType(ChatType.ChatRoom);
        }
        //发送消息
        EMClient.getInstance().chatManager().sendMessage(message);
        //刷新ui
        messageList.refreshSelectLast();
    }

在显示消息的 adpater 中,根据消息状态显示相应 UI 即可。

protected void handleTextMessage() {
        if (message.direct() == EMMessage.Direct.SEND) {
            setMessageSendCallback();
            switch (message.status()) {
            case CREATE: 
                progressBar.setVisibility(View.GONE);
                statusView.setVisibility(View.VISIBLE);
                break;
            case SUCCESS: // 发送成功
                progressBar.setVisibility(View.GONE);
                statusView.setVisibility(View.GONE);
                break;
            case FAIL: // 发送失败
                progressBar.setVisibility(View.GONE);
                statusView.setVisibility(View.VISIBLE);
                break;
            case INPROGRESS: // 发送中
                progressBar.setVisibility(View.VISIBLE);
                statusView.setVisibility(View.GONE);
                break;
            default:
               break;
            }
        }else{
            if(!message.isAcked() && message.getChatType() == ChatType.Chat){
                try {
                    EMClient.getInstance().chatManager().ackMessageRead(message.getFrom(), message.getMsgId());
                } catch (HyphenateException e) {
                    e.printStackTrace();
                }
            }
        }
    }