云之讯建议开发者不仅要关心如何使用云之讯sdk,同时也需要理解云之讯sdk的架构设计和内部实现原理,这样方便开发者排查问题。要理解云之讯sdk,需要开发者具有一定的开发经验和编程基础。
云之讯提供uikit sdk、im sdk、tcp sdk方便开发者调用,它们之间的关系可以用一幅图来表示:
这里以发送消息和收到消息为例,详解sdk之间的调用流程。
发送消息流程:
接受消息流程:
会话与消息属于一对多关系,消息不可能脱离会话而单独存在。消息可以根据targetId找到所属会话,会话也能通过targetId获取到消息列表。会话记录的入库操作是sdk自动完成的,当发送或者受到消息所属的会话不存在时会创建会话,否则只会更新会话。
对于发送消息来讲,只有sendMessage函数返回成功之后才会将消息记录入库。如果该消息所属会话不存在会创建会话,否则只会更新会话。待收到发送结果之后,会更新消息发状态和会话,同时回调下面两个函数:
对于接收消息来讲,sdk收到新消息自动将消息记录入库,如果该消息所属会话不存在会创建会话,否则只会更新会话,同时回调下面两个函数:
会话与消息更新流程:
消息与会话属于多对一关系,云之讯为了区分不同会话类型的消息,将消息又分为SingleChat(单聊消息)、DiscussionChat(讨论组消息)、GroupChat(群组消息)。开发者在发送消息时,应该可以根据会话类型创建不同的消息发送,也可以创建ChatMessage通过setCategoryId标识消息类型再发送,关系图如下:
在发送消息之前,开发者得新建一个消息对象,然后在调用云之讯sdk的sendMessage方法发送,以下是两种新建消息对象的方法:
方法一:
/** * 根据会话类型创建不同的消息 */ ChatMessage msg = null; switch (conversationinfo.getCategoryId()) { case PERSONAL: /** * 创建单聊消息 */ msg = new SingleChat(); break; case GROUP: /** * 创建群聊消息 */ msg = new GroupChat(); break; case DISCUSSION: /** * 创建讨论组消息 */ msg = new DiscussionChat(); break; }
方法二:
/** * 根据会话类型创建不同的消息 */ ChatMessage msg = new ChatMessage(); switch (conversationinfo.getCategoryId()) { case PERSONAL: /** * 设置消息类型为单聊 */ msg.setCategoryId(CategoryId.PERSONAL); break; case GROUP: /** * 设置消息类型为群聊 */ msg.setCategoryId(CategoryId.GROUP); break; case DISCUSSION: /** * 设置消息类型为讨论组 */ msg.setCategoryId(CategoryId.DISCUSSION); break; }
1) 发送文本消息
msg.setTargetId("接收方userId"); msg.setNickName("发送方昵称"); msg.setSenderId("发送方userId"); msg.setMsgType(MSGTYPE.MSG_DATA_TEXT); msg.setContent("消息内容"); msg.setFromMyself(true); IMManager.getInstance(mContext).sendmessage(msg)
2) 发送语音消息
msg.setTargetId("接收方userId"); msg.setNickName("发送方昵称"); msg.setSenderId("发送方userId"); msg.setMsgType(MSGTYPE.MSG_DATA_VOICE); msg.setContent("语音时间(如30)"); msg.setPath("语音文件路径"); IMManager.getInstance(mContext).sendmessage(msg)
3) 发送图片消息
msg.setTargetId("接收方userId"); msg.setNickName("发送方昵称"); msg.setSenderId("发送方userId"); msg.setMsgType(MSGTYPE.MSG_DATA_IMAGE); msg.setContent("要显示在页面的内容(如:图片)"); msg.setPath("图片文件路径"); IMManager.getInstance(mContext).sendmessage(msg)
4) 发送地图消息
/** * 构造地图对象。 * * @param latitude 地图经度。 * @param longitude 地图纬度。 * @param detailAddr 详细地址。 * @param thumbnailPath 地图截图路径。 */ LocationMapMsg locationMsg = new LocationMapMsg(latitude, longitude, detailAddr , thumbnailPath); msg.setTargetId("接收方userId"); msg.setNickName("发送方昵称"); msg.setSenderId("发送方userId"); msg.setMsgType(MSGTYPE.MSG_DATA_LOCALMAP); msg.setContent("要显示在页面的内容(如:地图)"); msg.setLocationMapMsg(locationMsg); IMManager.getInstance(mContext).sendmessage(msg)
5) 发送自定义消息
/** * 构造自定义对象。 * * @param data 要发送字节数组。 * @param length 字节数组长度。 */ CustomMsg customMsg = new CustomMsg(data, length); msg.setTargetId("接收方userId"); msg.setNickName("发送方昵称"); msg.setSenderId("发送方userId"); msg.setMsgType(MSGTYPE.MSG_DATA_CUSTOMMSG); msg.setContent("要显示在页面的内容(如:自定义消息)"); msg.setCustomMsg(customMsg) IMManager.getInstance(mContext).sendmessage(msg)
云之讯为了方便开发者能随时监听sdk的状态,提供了各式各样的监听回调,开发者需要根据自己的业务需求设置自己关心的回调事件,所有的设置监听事件都由IMManager控制类完成,这里需要注意的是:所有的监听回调都运行在子线程,开发者不应该在回调里面直接更新UI。
IMManager.getInstance(context).setSendMsgListener(new MessageListener(){ @Override public void onSendMsgRespone(ChatMessage msg) { /** * 发送消息结果回调,开发者应该更新发送状态 */ if(msg.getSendStatus() == ChatMessage.MSG_STATUS_SUCCESS){ Log.i("YZX","发送成功"); }else{ Log.i("YZX","发送失败"); } } @Override public void onReceiveMessage(List msgs) { /** * 接收到新消息回调,开发者应该将msgs添加到当前的消息集合,并刷新界面 */ } @Override public void onDownloadAttachedProgress(String msgId, String path, int totalSize,int currentProgress) { /** * 开发者调用了downloadAttached()接口下载后,sdk会回调该方法 */ } })
云之讯sdk在发送消息和收到消息时会更新会话,开发者需要设置会话回调,监听会话的更新、创建、和删除事件。
IMManager.getInstance(context).setConversationListener(new IConversationListener() { @Override public void onUpdateConversation(List conversations) { /** * 需要更新的会话集合,会话有可能是新创建的,有可能是更新的。 * 开发者需要根据targetId匹配上层应用会话集合。 * 如果targetId相同,则是更新会话,需要将sdk回调的会话替换掉上层应用的会话。 * 如果targetId不同,则是新创建的会话,添加到上层会话集合。 */ } @Override public void onUpdateConversation(ConversationInfo conversationInfo) { /** * nothing to do(兼容使用,开发者不用关心) */ } @Override public void onCreateConversation(ConversationInfo conversationInfo) { /** * nothing to do(兼容使用,开发者不用关心) */ } @Override public void onDeleteConversation(ConversationInfo conversationInfo) { /** * 当删除并退出讨论组的时候,sdk会删除会话,同时回调该事件 */ } });
开发者如果想监听sdk的状态可以设置该回调,当sdk状态发生改变时会回调该方法。
IMManager.getInstance(context).setISdkStatusListener(new ISdkStatusListener() { @Override public void onSdkStatus(UcsReason reason) { /** * sdk状态改变时回调,开发者可以通过reason.getReason()区分各个事件,下面是几种常见事件监听 */ if(reason.getReason() == UcsErrorCode.NET_ERROR_KICKOUT) { Log.i("YZX","服务器强制下线通知,账号在别处登录"); } else if(reason.getReason() == UcsErrorCode.NET_ERROR_TCPCONNECTOK){ Log.i("YZX","连接服务器成功"); } else if(reason.getReason() == UcsErrorCode.NET_ERROR_TCPCONNECTFAIL){ Log.i("YZX","连接服务器失败"); } else if(reason.getReason() == UcsErrorCode.NET_ERROR_TCPCONNECTING){ Log.i("YZX","正在连接服务器"); } else if(reason.getReason() == UcsErrorCode.PUBLIC_ERROR_NETUNCONNECT){ Log.i("YZX","网络断开"); } else if(reason.getReason() == UcsErrorCode.PUBLIC_ERROR_NETCONNECTED){ Log.i("YZX","网络连接上"); } } });
云之讯提供图片压缩、录音和播放、下载接口,方便开发者使用,开发者可以选择性使用云之讯sdk提供的工具。
云之讯sdk默认发送的图片不能超过20M,为了降低用户的流量,开发者需要将图片压缩后发送,这里云之讯提供了压缩接口方便使用。在使用前,开发者需要将下载的压缩包中libs目录下libjpegbither.so和libbitherjni.so文件,拷贝到自己工程的libs/armeabi/目录。
/** * 压缩图片并保存。 * * @param src 要压缩的图片源。 * @param quality 压缩的图片质量(0-100),100表示不压缩。 * @param savePath 压缩后图片保存路径。 */ IMManager.compressBitmap(src,quality,savePath)
开发者可以通过云之讯sdk完成音频的录制和播放,设置RecordListener监听录音完成和和播放录音完成,这里需要注意的是:RecordListener回调运行在子线程,开发者不应该在回调里面直接更新UI。
/** * 开始录音。 * * @param savePath 录音文件保存路径,不能为空。 * @param recordListener 录音回调事件,不能为空。 */ IMManager.getInstance(context).startVoiceRecord(savePath,new RecordListener() { @Override public void onFinishedRecordingVoice(int time) { /** * 调用stopVoiceRecord()方法后停止录音,sdk回调该事件返回录音时长 */ Log.i("YZX","录音时长:"+time+"秒...") } public void onFinishedPlayingVoice() { /** * nothing to do(录音不需要关注该方法) */ } }) /** * 停止录音。 * * 停止录音后,sdk会回调RecordListener的onFinishedRecordingVoice方法。 * 一般录音时长不超过60秒,开发者应该在60秒前调用stopVoiceRecord()停止录音。 */ IMManager.getInstance(context).stopVoiceRecord() /** * 开始播放录音。 * * @param srcPath 录音文件路径,不能为空。 * @param recordListener 录音回调事件,不能为空。 */ IMManager.getInstance(context).startPlayerVoice(srcPath,new RecordListener() { @Override public void onFinishedRecordingVoice(int time) { /** * nothing to do(播放录音不需要关注该方法) */ } public void onFinishedPlayingVoice() { /** * 播放录音完成之后回调该方法。 */ Log.i("YZX","play voice onFinished...") } }) /** * 停止播放录音。 * */ IMManager.getInstance(context).stopPlayerVoice()
为了方便开发者下载图片消息的原图,云之讯sdk提供下载接口方便调用,可以通过MessageListener监听下载进度和完成。
/** * 下载指定消息的文件,如某图片消息的原图。 * * @param url 文件url。 * @param savePath 文件要保存的路径。 * @param msgId 消息id。 * @param messageListener 下载消息监听。 */ IMManager.downloadAttached(url,savePath,msgId,new MessageListener(){ @Override public void onSendMsgRespone(ChatMessage msg) { /** * nothing to do(发送消息回调该事件) */ } @Override public void onReceiveMessage(List msgs) { /** * nothing to do(收到新消息回调该事件) */ } @Override public void onDownloadAttachedProgress(String msgId, String path, int totalSize,int currentProgress) { /** * 下载进度更新,当currentProgress >= totalSize,下载完毕 * 如果currentProgress == 0或者totalSize == 0下载失败 */ Log.i("YZX","文件总大小:"+totalSize+",当前下载进度:"+currentProgress); } })
开发者成功登录之后,不需要关心与服务器连接和断开,sdk会自动重连,以下是sdk断线重连机制:
重连场景 | 描述 |
---|---|
传输数据时,连接不可用 | 与服务器交互时,如果socket抛异常将会重连 |
服务器或者路由断开连接 | 服务器或者路由器判断当前连接无效,断开连接,sdk将会重连 |
心跳回执超时 | sdk发送心跳之后,30秒没有收到服务器回执,sdk将会重连 |
网络切换 | 断开网络之后,sdk将主动断开连接;网络链接成功之后,sdk将会重连。网络类型变化(如:3G切换到4G,移动网络切换到wifi网络等…),sdk也会重连。 |
连接失败 | 连接服务器失败之后,sdk默认会重连5次,重连间隔将会递增 |