Android SDK详解

云之讯建议开发者不仅要关心如何使用云之讯sdk，同时也需要理解云之讯sdk的架构设计和内部实现原理，这样方便开发者排查问题。要理解云之讯sdk，需要开发者具有一定的开发经验和编程基础。

一、架构设计

云之讯提供uikit sdk、im sdk、tcp sdk方便开发者调用，它们之间的关系可以用一幅图来表示：

1) TCP SDK：负责与服务器的交互，包括收发消息、断开与连接。

2) IM SDK：负责消息的存储和转发。

3) UIKIT SDK：负责上层UI的展示和用户自定义界面。

这里以发送消息和收到消息为例，详解sdk之间的调用流程。
发送消息流程：接受消息流程：

二、会话与消息

会话与消息属于一对多关系，消息不可能脱离会话而单独存在。消息可以根据targetId找到所属会话，会话也能通过targetId获取到消息列表。会话记录的入库操作是sdk自动完成的，当发送或者受到消息所属的会话不存在时会创建会话，否则只会更新会话。
对于发送消息来讲，只有sendMessage函数返回成功之后才会将消息记录入库。如果该消息所属会话不存在会创建会话，否则只会更新会话。待收到发送结果之后，会更新消息发状态和会话，同时回调下面两个函数：

1) onSendMsgRespone：将已经更新好的消息回调给开发者。

2) onUpdateConversation：将已经更新好的会话(该会话可能是创建也有可能是更新)回调给开发者。

对于接收消息来讲，sdk收到新消息自动将消息记录入库，如果该消息所属会话不存在会创建会话，否则只会更新会话，同时回调下面两个函数：

1) onReceiveMessage：将收到的消息回调给开发者。

2) onUpdateConversation：将已经更新好的会话(该会话可能是创建也有可能是更新)回调给开发者。

会话与消息更新流程：

1、消息体系

消息与会话属于多对一关系，云之讯为了区分不同会话类型的消息，将消息又分为SingleChat(单聊消息)、DiscussionChat(讨论组消息)、GroupChat(群组消息)。开发者在发送消息时，应该可以根据会话类型创建不同的消息发送，也可以创建ChatMessage通过setCategoryId标识消息类型再发送，关系图如下：

2、发送消息

在发送消息之前，开发者得新建一个消息对象，然后在调用云之讯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。

1、设置发送回调

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会回调该方法
           */		
	}
    })

2、设置会话回调

云之讯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会删除会话，同时回调该事件
	   */
	}    
});

3、设置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提供的工具。

1、图片压缩

云之讯sdk默认发送的图片不能超过20M，为了降低用户的流量，开发者需要将图片压缩后发送，这里云之讯提供了压缩接口方便使用。在使用前，开发者需要将下载的压缩包中libs目录下libjpegbither.so和libbitherjni.so文件，拷贝到自己工程的libs/armeabi/目录。

/**
 * 压缩图片并保存。
 *
 * @param src                     要压缩的图片源。
 * @param quality                 压缩的图片质量(0-100)，100表示不压缩。
 * @param savePath                压缩后图片保存路径。
*/
IMManager.compressBitmap(src,quality,savePath)

2、录音和播放

开发者可以通过云之讯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()

3、下载

为了方便开发者下载图片消息的原图，云之讯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次，重连间隔将会递增

消息

呼叫中心

互联网通信

流量

侧边栏

短信API

目录

Android SDK详解

一、架构设计

二、会话与消息

1、消息体系

2、发送消息

三、设置监听

1、设置发送回调

2、设置会话回调

3、设置sdk状态回调

四、工具说明

1、图片压缩

2、录音和播放

3、下载

五、断线重连

消息

呼叫中心

互联网通信

流量

侧边栏

短信API

用户工具

目录

Android SDK详解

一、 架构设计

二、 会话与消息

1、消息体系

2、发送消息

三、 设置监听

1、设置发送回调

2、设置会话回调

3、设置sdk状态回调

四、 工具说明

1、图片压缩

2、录音和播放

3、下载

五、 断线重连

页面工具

一、架构设计

二、会话与消息

三、设置监听

四、工具说明

五、断线重连