一步一步给你的Androidapp加入聊天功能.docx

1、一步一步给你的Androidapp加入聊天功能步一步给你的 Android app 加入聊天功能简介自去年 LeanCloud 发布实时通信（ IM ）服务之后，基于用 户反馈和工程师对需求的消化和对业务的提炼，上周正式发 布了实时通信 2.0 。设计理念依然是灵活、解耦、可 组合、可定制 ，具体可以参考实时通信开发指南 ，了解 LeanCloud 实时通信的基本概念和模型。下载和安装可以到 LeanCloud 官方下载点下载 LeanCloud IM SDK v2 版本。将下载到的 jar 包加入工程即可。Demo 及示例代码 如果您觉得一点点阅读文档较慢， 可以直接看我们的 Demo 代码

2、，并且下载自己运行一下试试看。一对一的文本聊天 我们先从最简单的环节入手，看看怎么用 LeanCloud IM SDK 实现一对一文本聊天。初始化和 LeanCloud 其他服务一样，实时聊天服务的初始化也是在 Application 的 onCreate 方法中进行的：public class MyApplication extends Applicationpublic void onCreate()AVOSCloud.initialize(this,appId,appKey);并且在 AndroidManifest.xml 中间声明：接下来我们开始一步一步接入聊天服务 登录用户在开始聊天

3、之前，需要先登录 LeanCloud 云端。这个 登录并不需要用户名、密码认证，只是与 LeanCloud 云端 建立一个长连接，所以只需要传入一个可唯一标识当前用户 的 clientId 即可。在本 SDK 中，我们会为每一个终端用户开启一个AVIMClient 实例，获取这一实例的方法位于 com.avos.avoscloud.im.v2.AVIMClient 类中，其声明如下： public static AVIMClient getInstance(String clientId)SDK 内部会为每一个 clientId 创建唯一的 AVIMClient 实 例，同一个 clientI

4、d 多次调用该方法，得到的都是同一个结 果。所以如果要支持同一个客户端内多账号登录，只要使用 不同的 clientId 多次调用该方法即可。 LeanCloud IM SDK 本身是支持多账户同时登录的。得到 AVIMClient 实例之后，我们需要登录 LeanCloud 云 端。 这是通过调用 AVIMClient 的 open 方法实现的， 其声 明如下：public void open(final AVIMClientCallback callback)open 函数返回的时候，会把 AVIMClient 实例和AVException 信息(如果发生错误的话)传给 AVIMClient

5、Callback 回调接口。 好了，我们现在来实际看一下这个过程如何实现。假定聊天 发起方名叫 Tom ，为直观起见，我们使用用户名来作为 clientId 登录聊天系统 ( LeanCloud 云端只要求 clientId 在 应用内唯一即可，具体用什么数据由应用层决定) ，代码如 下：AVIMClient imClient = AVIMClient.getInstance(Tom); imClient.open(new IMClientCallback()Overridepublic void done(AVIMClient client, AVException e) if (null

6、!= e) / 出错了，可能是网络问题无法连接 LeanCloud 云 端，请检查网络之后重试。/ 此时聊天服务不可用。e.printStackTrace(); else / 成功登录，可以开始进行聊天了(假设为MainActivity )。Intent intent = new Intent(currentActivity,MainActivity.class);currentActivity.startActivity(intent););建立对话在本版本 IM SDK 中，开始聊天之前， 需要先创建或者加入 一个对话 ( AVIMConversation )，所有消息都是由某个 clie

7、nt 发往一个对话 ，对话内的所有成员会实时收到 新消息。对话支持如下默认属性：conversationId ，字符串，对话 id ，只读，对话创建之后由 LeanCloud 云端赋予一个全局唯一的 id 。creator ，字符串，对话创建者的 clientId ，只读，标识对话 创建者信息members ，数组，对话参与者，这里记录了所有的参与者 name ，字符串，对话的名字，可选，可用来对于群组命名 attributes ， Map/Dict ，自定义属性，可选，供开发者自己扩 展用。transient ，布尔值，表示对话是否为暂态对话(关于暂态对 话，后面会详细解释)我们可以通过 A

8、VIMClient 来创建一个对话，其函数声明为： /指定成员、自定义属性，创建对话 public void createConversation(final List conversationMembers, final Map attributes, final AVIMConversationCreatedCallback callback);/指定成员、名字、自定义属性，创建对话public void createConversation(final List conversationMembers, String name, final Map attributes, final A

9、VIMConversationCreatedCallback callback);/指定成员、名字、自定义属性和对话标志，创建对话 public void createConversation(final List conversationMembers, String name, final Map attributes, final boolean isTransient, finalAVIMConversationCreatedCallback callback);各参数的含义如下：conversationMembers - 对话初始成员列表，可以为空name 对话的名字，可选isTra

10、nsient 是否为暂态对话标志，默认为 false callback 结果回调接口，在创建结束之后调用，通知开 发者成功与否接下来我们看看实际如何创建一个对话。 假定我们要跟 Bob 这个用户进行聊天，我们先创建一个对话，代码如下：List clientIds = new ArrayList();clientIds.add(Tom);clientIds.add(Bob);/ 我们给对话增加一个自定义属性 type ，表示单聊还是群聊/ 常量定义：/ int ConversationType_OneOne = 0; / 两个人之间的单聊/ int ConversationType_Group

11、= 1; / 多人之间的群聊Map attr = new HashMap();attr.put(type, ConversationType_OneOne);imClient.createConversation(clientIds, attr, new AVIMConversationCreatedCallback() Overridepublic void done(AVIMConversation conversation,AVException e) if (null != conversation) / 成功了， 这时候可以显示对话的 Activity 页面 (假 定为 ChatAc

12、tivity )了。Intent intent = new Intent(this, ChatActivity.class);Intent.putExtra( “ conversation ” , conversation);startActivity(intent); );建立的对话在控制台怎么查看如你所见， 我们创建一个对话的时候， 指定了成员 （Tom 和 Bob ）和一个额外的属性（ type: 0 ）。这些数据保存到云端 后，你在 控制台 - 存储 - 数据 里面会看到， _Conversation 表中增加了一条记录，新记录的 m 属性值 为Tom, Bob , attr 属性值为

13、type:。如你所料，m 属 性就是对应着成员列表， attr 属性就是用户增加的额外属性 值（以对象的形式存储） 。发送消息 通过 AVIMConversation 的 sendMessage 族方法，可以 将消息发往目标对话。方法声明如下：/ 直接发送一条消息，在大多数情况下，你该调用这个方法 public void sendMessage(AVIMMessage message, final AVIMConversationCallback callback);/ 发送消息时，指定特殊的消息选项，用来发送特别的消息 public void sendMessage(final AVIMMe

14、ssage message, final int messageFlag, final AVIMConversationCallback callback);各参数的含义如下：message - 消息实例messageFlag 消息选项(普通消息，暂态消息，待回执 消息)，可选，默认值是普通消息callback 结果回调接口，在发送结束之后调用，通知开 发者成功与否接下来我们试着发送一条普通文本消息。示例代码如下： AVIMMessage message = new AVIMMessage(); message.setContent(hello);conversation.sendMessag

15、e(message, newAVIMConversationCallback() Overridepublic void done(AVException e) if (null != e) / 出错了。e.printStackTrace(); else Logger.d( 发送成功， msgId= + message.getMessageId(););好了，这样一条消息就发送过去了。 但是问题来了， 对于 Bob 而言，他怎么才能收到别人发给他的消息呢？消息接收在 Bob 这一端，要能接收到消息，需要如下几步： 1，进行初始化；2，准备好自己的 AVIMMessageHandler ，响应新

16、消息到达 通知。在本版本 IM SDK 中，我们设计的框架是将消息类型与具体 的 handler 类绑定起来， 这样开发者可以为不同类型的消息 设置不同的 handler ，处理起来更加灵活自由。这一绑定过 程是通过com.avos.avoscloud.im.v2.AVIMMessageManager 类的 void registerMessageHandler(Class clazz,MessageHandler handler) 函数实现的。 AVIMMessageManager 类中还有一个方法 void registerDefaultMessageHandler(AVIMMessage

17、Handler handler) 则用来指定全局默认的消息处理 handler 。AVIMMessageHandler 的主要函数如下： public void onMessage(AVIMMessage message, AVIMConversation conversation, AVIMClient client); 对于 Tom 发过来的消息，要接收并显示出来，我们只需实 现 onMessage 方法即可，示例代码如下： class CustomMessageHandler extendsAVIMMessageHandler Overridepublic void onMessage(

18、AVIMMessage message, AVIMConversation conversation, AVIMClient client) / 新消息到来了。在这里增加你自己的处理代码。String msgContent = message.getContent();Logger.d(conversation.getConversationid() + 收到一 条新消息： + msgContent);3，进行登录，代码也与发送端一样。Bob 这边要接收到 Tom 发过来的消息，其完整流程如下：/ 自定义消息响应类class CustomMessageHandler extendsAVIMMe

19、ssageHandler Overridepublic void onMessage(AVIMMessage message,AVIMConversation conversation, AVIMClient client) / 新消息到来了。在这里增加你自己的处理代码。String msgContent = message.getContent();Logger.d(conversation.getConversationid() + 收到一 条新消息： + msgContent);/ application 的初始化部分 public void onCreate()AVOSCloud.in

20、itialize(this,appId,appKey);AVIMMessageManager.registerDefaultMessageHandler(n ew CustomMessageHandler();/ 用户登录部分AVIMClient imClient = AVIMClient.getInstance(Bob); imClient.open(new IMClientCallback()Overridepublic void done(AVIMClient client, AVException e) if (null != e) / 出错了，可能是网络问题无法连接 LeanClou

21、d 端，请检查网络之后重试。/ 此时聊天服务不可用。e.printStackTrace(); else / 成功登录，可以开始进行聊天了。;);注意！AVIMMessageManager.registerDefaultMessageHandler() 一定要在 AVIMClient.open() 之前调用， 否则可能导致服务 器发回来的部分消息丢失。退出登录在 app 退出的时候，或者切换用户的时候，我们需要断开 与 LeanCloud 实时通信服务的长连接，这时候需要调用 AVIMClient.close(final AVIMClientCallback callback) 函数。 一般情况

22、下，这个函数都会关闭连接并立刻返回，这时候 Leancloud 实时通信服务端就会认为当前用户已经下线。 几个主要的回调接口 从上面的例子中可以看到，要接收到别人给你发送的消息， 需要重载 AVIMMessageHandler 类。从 v2 版开始， LeanCloud IM SDK 大量采用回调来反馈操作结果，但是对 于一些被动的消息通知，则还是采用接口来实现的，包括：当前网络出现变化 对话中有新的消息 对话中有新成员加入 对话中有成员离开 被邀请加入某对话 被踢出对话LeanCloud IM SDK 内部使用了三种接口来响应这些事件。网络事件响应接口 主要用来处理网络变化事件，接口定义在A

23、VIMClientEventHandler ，主要函数为：void onConnectionPaused(AVIMClient client) 指网络连接断开事件发生，此时聊天服务不可用。void onConnectionResume(AVIMClient client) 指网络连接恢复正常，此时聊天服务变得可用。在网络中断的情况下，所有的消息收发和对话操作都会出现 问题。通过AVIMClient.setClientEventHandler(AVIMClientEventHandler handler) 可以设定全局的 ClientEventHandler 。 对话成员变化响应接口 主要用来处

24、理对话中成员变化的事件，接口定义在AVIMConversationEventHandler, 主要函数为：onMemberLeft(AVIMClient client, AVIMConversationconversation, List members, String kickedBy) 对话中有成员离开时所有剩余成员都会收到这一通知。参数意义说明如 下： client 指已经登录的 client ，因为支持一个客户端多账 户登录，每个账户会对应一个 client conversation 指目标对话； members 指离开的成员列表； kickedBy 表示踢人者的 id ； onMem

25、berJoined(AVIMClient client, AVIMConversation conversation, List members, String invitedBy) 对话中有新成员加入时所有成员都会收到 这一通知。参数意义说明如下： client 指已经登录的 client ， 因为支持一个客户端多账户登录，每个账户会对应一个 client conversation 指目标对话； members 指加入的新成员列表； invitedBy 表示邀请者的 idonKicked(AVIMClient client, AVIMConversation conversation, St

26、ring kickedBy) 当前用户被踢出对话的通知，参数意义说明如下： client 指已经登 录的 client ，因为支持一个客户端多账户登录，每个账户会 对应一个 client conversation 指目标对话；kickedBy 表示踢人者的 idonInvited(AVIMClient client,AVIMConversation conversation, String operator) 当前用 户被邀请加入对话的通知。参数意义说明如下： client 指已 经登录的 client ，因为支持一个客户端多账户登录，每个账 户会对应一个 client conversatio

27、n 指目标对话； operator 表示邀请者的 id 通过 AVIMMessageManager.setConversationEventHandler(AV IMConversationEventHandler handler) 可以设置全局的 ConversationEventHandler 。消息响应接口 主要用来处理新消息到达事件，接口定义在 MessageHandler ，AVIMMessageHandler 是一个空的实现 类，我们应该通过重载 AVIMMessageHandler 的相关方法 来完成消息处理。主要的方法有：onMessage(AVIMMessage messag

28、e, AVIMConversation conversation, AVIMClient client) 指接收到新的消息。参数 意义说明如下： client 指已经登录的 client ，因为支持一个 客户端多账户登录，每个账户会对应一个 client conversation 指目标对话；自己message 表示消息实例 onMessageReceipt(AVIMMessage message, AVIMConversation conversation, AVIMClient client) 发送的消息被对方接收时会收到此通知，各参数意义同上。通过 AVIMMessageManager.

29、registerDefaultMessageHandler(h andler) 可以设置全局的 MessageHandler 。 我们实现这三类接口，就可以处理所有的通知消息了。示例 代码如下：/ 处理网络状态变化事件class CustomNetworkHandler extendsAVIMClientEventHandler Overridepublic void onConnectionPaused(AVIMClient client) / 请按自己需求改写Logger.d(connect paused);Overridepublic void onConnectionResume(AV

30、IMClient client) Logger.d(connect resume);/ 处理对话成员变化事件class CustomConversationHandler extendsAVIMConversationEventHandler public private Context gContext = null;private void toast(String str) Toast.makeText(gContext, str,Toast.LENGTH_SHORT).show();private void toast(Context context, String str) Toas

31、t.makeText(context, str,Toast.LENGTH_SHORT).show();Overridepublic void onMemberLeft(AVIMClient client, AVIMConversation conversation, List members, String kickedBy) 用来用来toast(MsgUtils.nameByUserIds(members) + left,kicked by + MsgUtils.nameByUserId(kickedBy);/注： MsgUtils 是一个辅助类， nameByUserIds 将 userId 转换成用户名Overridepublic void onMemberJoined(AVIMClient client, AVIMConversation co