注册 登录

用户工具

您在这里: 接入建议 » IM SDK详解
im_sdk详解

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

im_sdk详解 [2017/08/23 08:44]
 im_sdk详解 [2017/08/23 08:44] (当前版本)
行 1: 行 1:
 +====== IM SDK详解 ======
 +本文档将详细介绍云之讯IMSDK和TCPSDK的知识，包括架构、消息体系、消息收发流程等，您可以在阅读本文档后对云之讯IM有更深的了解，方便您更快的开发自己的产品。
 +{{  :​imsdk详解01.png?​nolink& ​ }}\\
 +  ***IMSDK**
 +  *IMSDk封装了会话、消息等各种IM业务对象，处理IM业务逻辑,​对外提供IM业务能力接口。开发者调用SDK接口，快速集成IM业务能力。主要特点是接口清晰，利于理解。
 +
 +  ***TCPSDK**
 +  *TCPSDK为IMSDK提供了基本的通信能力,​封装登陆云平台、异常重连等功能，并对外提供通信能力接口。IMSDK需要依赖于TCPSDK。
 +===== 一、IMSDK核心类 =====
 +**UCSIMClient**是IMSDK的核心类。IMSDK提供的所有能力，都需要通过UCSIMClient的实例去调用。
 +===== 二、会话实体类 =====
 +**UCSConversation** 是会话实体类，首先您需要充分的了解 UCSConversation（会话） 和 UCSMessage（消息） 两个实体类的关系。\\
 +会话实体类是用来存储本地会话的容器类，消息实体类是用来存储本地消息的容器类。会话有多种类型，可以是单聊会话，也可以是群组会话等，每一个 UCSConversation（会话）包含多条 UCSMessage（消息），关系如下图所示：\\
 +{{  :​imsdk详解02.png?​nolink& ​ }}\\
 +
 +通过 conversationType 和 targetId，您可以标识当前账号唯一的一个会话。ConversationType 枚举值意义和对应的 targetId 意义为：
 +^ 会话类型枚举值 ​      ^ 类型说明 ​        ^ targetId说明 ​      ^
 +| UCS_IM_SOLOCHAT ​       | 单聊，用户间一对一聊天 ​        | 对方的userId ​      |
 +| UCS_IM_GROUPCHAT ​       | 群聊 ​  ​|群Id |
 +| UCS_IM_DISCUSSIONCHAT ​       | 讨论组聊天 ​        | 讨论组Id ​      |
 +| UCS_IM_SYSTEMMSG ​       | 系统会话 ​        | 系统账户的Id ​     |
 +|UCS_IM_Broadcast ​        ​|广播会话 ​         | 广播账户的Id |
 +
 +  *通过一个 conversationType 和 targetId 组合，您可以确定一个唯一的会话。如当您需要发起单聊会话时，您需要传入 UCS_IM_SOLOCHAT 和 userId，当您需要发起群组聊天时，您需要传入 UCS_IM_GROUPCHAT 和 groupId，当您需要发起讨论组会话时，您需要传入 UCS_IM_DISCUSSIONCHAT 和 discussionId。
 +
 +===== 三、消息实体类 =====
 +UCSMessage是一个消息实体类，包含了描述一条消息的所有属性。
 +   ​*消息对应的会话类型(conversationType)。单聊会话、讨论组会话、群会话等。
 +   ​*消息的内容类型(messageType)。文本、语音、图片、地图等
 +   ​*消息接收者(receiveId)。如果这条消息是群组消息，receiveId是群id;​如果这条消息是单聊消息，receveId是消息接收者的id;​如果这条消息是讨论组消息，receveId是讨论组Id
 +   ​*消息的唯一标识(messageId)。这个标识在每个账号上是唯一的。
 +   ​*消息的方向(messageDirection)。这个属性可以用来判断消息是不是自己发出的。
 +   ​*消息的发送者(senderUserId)。这条消息是谁发的
 +   ​*发送者的昵称(senderNickName)。这个有可能为空,​取决于客户端的APP Server有没有给云之讯平台传对应的昵称。
 +   ​*消息发送状态(sentStatus)。这条消息的发送状态
 +   ​*消息接收状态(receivedStatus)。这条消息在本地的接收状态。
 +   ​*消息内容(content)。这个字段包含一个UCSMsgContent的子类的对象。如果这个会话对应的消息类型是文本，那么这个字段存储的就是一个UCSTextMsg类型的对象；如果是图片，就是一个UCSImageMsg类型的对象；如果是语音，就是一个UCSVoiceMsg类型的对象。开发者可以解析这个对象，然后自定义展示在UI上。
 +   ​*objectName、extra。这两个是保留字段，暂时未使用。
 +
 +UCSMessage所有的属性，开发者只需要进行读取就可以，不要进行赋值。
 +
 +===== 四、消息内容类 =====
 +==== 1、UCSMsgContent 消息内容基类====
 +UCSMsgContent是一个消息内容的基类,​作为UCSTextMsg、UCSImageMsg等消息内容类的父类。
 +<code java>
 +pushContent ​  ​云之讯服务器下发的内容,​比如收到一条文本消息，这个pushContent的内容为"​您有一条新的文本消息"​。
 +rawData ​    ​保留字段，未使用
 +</​code>​
 +消息内容类不同于消息实体类（UCSMessage），消息内容类代表一条具体的消息内容，而消息实体类是消息类的外层容器，消息实体对象是消息对象在本地存储的外层对象，消息实体对象除了包含消息对象外，还包括消息的方向、接收状态、接收时间、发送者等。\\
 +当前版本的消息分两种，普通的内容类消息，和通知类消息，接下来将分别仔细介绍。\\
 +^ 消息内容分类 ​      ^ 对应的内容类 ​     ^
 +| 内容类 ​       | 表示一个用户间发送的包含具体内容的消息，需要展现在聊天界面上，如文字消息(UCSTextMsg)、语音消息(UCSVoiceMsg)等。 ​    |
 +| 通知类 ​       | 表示一个通知信息，可能展现在聊天界面上，如讨论组通知(UCSDiscussionNotification)。 ​     |
 +
 +==== 2、UCSTextMsg 文本内容类==== ​
 +UCSTextMsg。用来发送文字类消息，其中可以表情。继承自UCSMsgContent，是一个文本内容类。
 +<code java>
 +content是消息文字内容,​您可以传入字节数不大于1500的任意文本。
 +extra暂时未被使用,​您可以直接忽略。
 +为了使用方便，建议您直接使用类方法initWithContent:​构建整个对象。
 +</​code>​
 +演示代码如下:​
 +<code java>
 +    //​给id为@"​123456789"​的用户发送一条文本消息
 +    UCSTextMsg *textMessage = [UCSTextMsg initWithContent:​@"​文本消息内容,​字节长度请不要超过1500"​];​
 +    [[UCSIMClient sharedIM] sendMessage:​UCS_IM_SOLOCHAT receiveId:​@"​123456789"​ msgType:​UCS_IM_TEXT content:​textMessage success:​^(long long messageId) {
 +        NSLog(@"​文本消息发送成功"​);​
 +    } failure:​^(UCSError *error, long long messageId) {
 +        NSLog(@"​文本消息发送失败,​失败原因error:​%@",​ error);
 +    }];
 +</​code>​
 +
 +==== 3、UCSVoiceMsg 语音内容类==== ​
 +UCSVoiceMsg。语音内容类，继承自UCSMsgContent。发送语音时，填充 amrAudioData、duration这两个字段,​voicePath不需要填充。接收语音时 或者 获取聊天记录时，voicePath、duration这两个字段有值,​amrAudioData为空。\\
 +<code java>
 +amrAudioData ​  ​AMR格式的data。(发送语音的时，必填)
 +voicePath ​ 语音的本地路径。(接收语音时，这个参数存放语音在本地的地址)
 +duration ​  ​语音时长。(发送语音时，必填)
 +extra      保留字段,​暂时未被使用
 +为了使用方便，建议您直接使用initWithAmrAudioData:​duration:​构建整个对象。
 +</​code>​
 +演示代码如下:​
 +<code java>
 +    //​给id为@"​28565844"​的讨论组发送一条长度为10s的语音消息
 +    UCSVoiceMsg *voiceMessage = [UCSVoiceMsg initWithAmrAudioData:​voiceData duration:​10.0];​
 +    [[UCSIMClient sharedIM] sendMessage:​UCS_IM_DISCUSSIONCHAT receiveId:​@"​28565844"​ msgType:​UCS_IM_VOICE content:​voiceMessage success:​^(long long messageId) {
 +        NSLog(@"​语音消息发送成功"​);​
 +    } failure:​^(UCSError *error, long long messageId) {
 +        NSLog(@"​语音消息发送失败,​失败原因error:​%@",​ error);
 +    }];
 +</​code>​
 +
 +==== 4、UCSImageMsg 图片消息内容类 ====
 +UCSImageMsg。图片内容类，继承自UCSMsgContent。
 +<code java>
 +thumbnailLocalPath ​ 缩略图本地路径。
 +imageRemoteUrl ​ 大图的远程url。自己发送的图片消息，这个字段为空。
 +imageLocalPath ​ 大图的本地路径。收到的图片消息，这个字段为空。
 +originalImage ​ 原图。(发送图片时，只需要给这个参数赋值就行，其他的参数不需要赋值)。发送时必填。
 +                当收到别人的图片消息时，这个字段为空。获取图片可以通过imageRemoteUrl这个参数自定义下载。
 +                当取出聊天的历史消息时，无论消息是发送的还是接收的，这个参数都为空。
 +                自己发送的图片可以通过imageLocalPath这个参数去获取，接收的图片可以imageRemoteUrl这个参数去获取。
 +extra  保留字段,​暂时未被使用
 +为了使用方便，建议您直接使用initWithOriginalImage:​构建整个对象
 +</​code>​
 +演示代码如下:​
 +<code java>
 +    //​给id为@"​abc"​的群发送一张图片
 +    UIImage *image = [UIImage imageNamed:​@"​test.jpg"​];​
 +    UCSImageMsg * imageMessage = [UCSImageMsg initWithOriginalImage:​image];​
 +    [[UCSIMClient sharedIM] sendMessage:​UCS_IM_GROUPCHAT receiveId:​@"​abc"​ msgType:​UCS_IM_IMAGE content:​imageMessage success:​^(long long messageId) {
 +        NSLog(@"​图片发送成功"​);​
 +    } failure:​^(UCSError *error, long long messageId) {
 +        NSLog(@"​图片发送失败,​失败原因error:​%@",​ error);
 +    }];
 +</​code>​
 +====5、UCSLocationMsg 地理位置内容类 ==== 
 +UCSLocationMsg。地理位置内容类，继承自UCSMsgContent。
 +<code java>
 +latitude ​ 纬度
 +longitude 经度
 +coord_type ​ 坐标类型。如果开发者不使用可以置空。
 +address ​ 地址信息
 +thumbnailImage ​ 位置缩略图
 +为了使用方便，建议您直接使用initWithLatitude:​longitude:​address:​locationImage:​coord_type:​构建整个对象
 +</​code>​
 +演示代码如下:​
 +<code java>
 +    //​给id为@"​abc"​的群发送一个地理位置信息
 +    UIImage *locationImage = [UIImage imageNamed:​@"​位置缩略图.jpg"​];​
 +    UCSLocationMsg *locationMessage = [UCSLocationMsg initWithLatitude:​30.00 longitude:​30.00 address:​@"​我的位置"​ locationImage:​locationImage coord_type:​nil]
 +    [[UCSIMClient sharedIM] sendMessage:​UCS_IM_GROUPCHAT receiveId:​@"​abc"​ msgType:​UCS_IM_Location content:​locationMessage success:​^(long long messageId) {
 +        NSLog(@"​位置发送成功"​);​
 +    } failure:​^(UCSError *error, long long messageId) {
 +        NSLog(@"​位置发送失败,​失败原因error:​%@",​ error);
 +    }];
 +</​code>​
 +
 +====6、UCSCustomMsg 自定义内容类 ====
 +UCSCustomMsg。自定义内容类。当您发送自定义消息时，需要将需要发送的内容转成NSData类型的字节流，接收者收到的同样是NSData类型的字节流，整个加密解密的过程由开发者自己处理，SDK仅仅作为一个传输的通道。
 +<code java>
 +data   ​传输的字节流。大小请不要超过64K。
 +为了使用方便，建议您直接使用initWithData:​构建整个对象
 +</​code>​
 +<code java>
 +    //​给id为@"​123456789"​的讨论组发送一条自定义消息。
 +    // base64加密这段文字，GTMBase64是一个开源加密库，开发者可以选择任意加密方式。
 +    NSString *text = @"​开发者可以根据自己的需求，将图片、语音、文本等数据加密成NSData类型的数据,​构建自定义消息。云之讯SDK只负责传输这条消息，加密、解密的过程完全由开发者完成。"​
 +    NSString * base64Str = [GTMBase64 encodeBase64String:​text];​
 +    NSData * data = [base64Str dataUsingEncoding:​NSUTF8StringEncoding];​
 +    ​
 +    //​构建自定义消息
 +    UCSCustomMsg * customMsg = [[UCSCustomMsg alloc] initWithData:​data];​
 +    [[UCSIMClient sharedIM] sendMessage:​UCS_IM_DISCUSSIONCHAT receiveId:​@"​123456789"​ msgType:​UCS_IM_Custom content:​customMsg success:​^(long long messageId) {
 +        NSLog(@"​发送成功"​);​
 +    } failure:​^(UCSError *error, long long messageId) {
 +        NSLog(@"​发送失败,​失败原因error:​%@",​ error);
 +    }]
 +</​code>​
 +====7、UCSDiscussionNotification 讨论组通知内容类 ==== 
 +UCSDiscussionNotification是讨论组通知内容类。讨论组通知由服务器下发，您不需要去发送通知。
 +<code java>
 +operatorId 讨论组的id
 +extension ​ 扩展字段，用于存储服务器下发扩展信息。比如“张三 移除了 李四”。
 +</​code>​
  

页面工具