这里会显示出您选择的修订版和当前版本之间的差别。
|
im_sdk集成 [2016/04/11 08:41] liuxia 创建 |
im_sdk集成 [2017/08/23 08:44] |
||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | ====== IM SDK集成 ====== | ||
| - | 在您阅读此文档之前，我们假定您已经具备了基础的 iOS 应用开发经验，并且理解即时通讯的相关概念。 | ||
| - | ===== 一、前期准备 ===== | ||
| - | ==== 1、注册开发者账号 ==== | ||
| - | 开发者账号是开发者管理应用的主账号，您需要拥有一个开发者账号才能开始创建应用。如果您还未注册，或者希望使用新的账号创建应用，请前往[[http://www.ucpaas.com/user/toSign|云之讯账户系统]]注册开发者账号。\\ | ||
| - | {{ :云之讯通行证注册_0.png?nolink& }}\\ | ||
| - | 注册时,请您使用真实的手机号码和邮箱，以方便我们向您发送重要通知并在紧急时刻能够联系到您。\\ | ||
| - | {{ :云之讯通行证注册_1.png?nolink& }}\\ | ||
| - | |||
| - | 如果您想了解更多,请前往[[http://docs.ucpaas.com/doku.php?id=%E6%96%B0%E6%89%8B%E6%8C%87%E5%BC%95|云之讯开发者账户指南]]。\\ | ||
| - | |||
| - | ==== 2、创建应用 ==== | ||
| - | 完成开发者账号注册后，在为您的APP集成云之讯能力之前，您需要前往[[http://www.ucpaas.com/user/account|云之讯开发者控制台]]创建应用，这个应用和您需要集成云之讯能力的APP是**一对一**的对应关系。\\ | ||
| - | {{ :云之讯控制台_0.png?nolink& }}\\ | ||
| - | 您可以点击页面左上方<html><font color = red>创建应用</font></html>按钮开始创建一个应用。在创建应用界面，您需要填写<html><font color = red>应用名称、应用类型、所属行业</font></html>三个必选项。云之讯强烈建议您设置<html><font color = red>服务器白名单</font></html>，设定白名单地址后，云之讯服务器在识别该应用请求时将只接收白名单内服务器发送的请求，能有效提升帐号安全性。 如未设置默认不生效。如果您的应用需要使用到<html><font color = red>高级配置</font></html>中的能力，您需要勾选对应的能力项。\\ | ||
| - | {{ :云之讯控制台_1.png?nolink& }}\\ | ||
| - | |||
| - | 如果您想了解更多,请前往[[http://docs.ucpaas.com/doku.php?id=%E7%AE%A1%E7%90%86%E4%B8%AD%E5%BF%83%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97|云之讯管理平台使用指南]]。\\ | ||
| - | |||
| - | ==== 3、下载、导入SDK ==== | ||
| - | 在单独集成云之讯IM通讯能力的情况下，您需要用到<html><font color = red>云之讯IMSDK</font></html>和<html><font color = red>云之讯TCPSDK</font></html>两份SDK。如果您对<html><font color = red>云之讯TCPSDK</font></html>仍有疑问，可以前往[[http://172.16.5.37:1122/doku.php?id=im_sdk%E8%AF%A6%E8%A7%A3|SDK详解]]了解。\\ | ||
| - | ===1、下载SDK=== | ||
| - | 您可以到[[http://www.ucpaas.com|云之讯官网]]下载SDK | ||
| - | {{ :云之讯下载sdk_0.png?nolink& }} | ||
| - | ===2、SDK目录讲解=== | ||
| - | **云之讯 IMSDK**文件结构说明(以<html><font color = red>版本v3.0.4</font></html>为例,后续版本可能有小的变动)\\ | ||
| - | {{ :imv3.0.4.0文件结构.png?nolink& }} | ||
| - | lib静态库 | ||
| - | <code objc> | ||
| - | libucsimlib.a 整个IMSDK的库文件，消息业务逻辑处理的库 | ||
| - | </code> | ||
| - | 头文件 | ||
| - | <code objc> | ||
| - | UCSIMSDK.h 包含整个IMSDK的头文件，使用时请import这个文件 | ||
| - | UCSIMClient.h 包含IMSDK的核心能力接口，比如发消息、获取会话列表等。 | ||
| - | UCSIMClientDelegate.h 包含IMSDK的回调接口，回调服务器返回到SDK的信息。比如接收到服务器返回的消息、接收到服务器返回的错误等。 | ||
| - | UCSIMDefine.h 包含IMSDK的一些定义。比如聊天类型、会话类型、消息发送状态等。 | ||
| - | UCSConversation.h 会话类型 | ||
| - | UCSDiscussion.h 讨论组类型 | ||
| - | UCSMessage.h 消息类型，包含一条消息的所有属性 | ||
| - | UCSUserInfo.h 用户信息类 | ||
| - | UCSMsgContent.h 消息内容基类 | ||
| - | UCSTextMsg.h 文本消息类，UCSMsgContent的子类 | ||
| - | UCSImageMsg.h 图片消息类，UCSMsgContent的子类 | ||
| - | UCSVoiceMsg.h 语音消息类，UCSMsgContent的子类 | ||
| - | UCSLocationMsg.h 地理位置消息类，UCSMsgContent的子类 | ||
| - | UCSDiscussionNotification.h 讨论组通知类，UCSMsgContent的子类 | ||
| - | UCSNotificationMessage.h 通知消息类，UCSMsgContent的子类 | ||
| - | UCSCustomMsg.h 自定义消息类，UCSMsgContent的子类 | ||
| - | UCSUnknownMsg.h 未知消息类。(高版本的SDK可能会增加新的消息类型，低版本使用未知消息类型兼容识别不了的新类型) | ||
| - | </code> | ||
| - | |||
| - | |||
| - | **云之讯 TCPSDK**文件说明(以<html><font color = red>版本V3.0.4</font></html>为例,后续版本可能有小的变动)\\ | ||
| - | {{ :tcpsdkv3.0.4.0文件结构.png?nolink& }} | ||
| - | lib静态库 | ||
| - | <code objc> | ||
| - | libucstcplib.a 整个TCPSDK的库文件,与云平台进行通讯的库 | ||
| - | </code> | ||
| - | 头文件 | ||
| - | <code objc> | ||
| - | UCSTCPSDK.h 包含TCPSDK所有头文件，使用时请import这个文件 | ||
| - | UCSTcpClient.h 包含TCPSDK的核心能力接口，比如登陆云平台、注销云平台等。 | ||
| - | UCSTcpClientDelegate.h 包含TCPSDK的事件回调接口 | ||
| - | UCSTcpDefine.h TCP相关的一些定义 | ||
| - | UCSError.h SDK错误信息定义类 | ||
| - | </code> | ||
| - | |||
| - | ===3、IMSDK、TCPSDK的关联== | ||
| - | 如果您是第一次接入云之讯服务，可能会对<html><font color = red>TCPSDK</font></html>感到陌生。云之讯平台提供<html><font color = red>IM通讯</font></html>、<html><font color = red>Voip通讯</font></html>等能力，这些能力都要和云之讯服务器进行交互，包括登陆、重连、断开等。我们将这部分共有的能力抽取出来，封装成<html><font color = red>TCPSDK</font></html>。\\ | ||
| - | <html><font color = red>TCPSDK</font></html>专注于和服务器之间的连接交互，<html><font color = red>IMSDK</font></html>专注于IM业务的逻辑处理，<html><font color = red>VoipSDK</font></html>专注于Voip业务的逻辑处理。这些能力SDK之间可以自由组合。如果您需要同时集成IM和Voip能力，那么您需要组合<html><font color = red>TCPSDK + IMSDK + VoipSDK</font></html>。如果您仅仅需要集成IM能力，那么您仅需要组合<html><font color = red>TCPSDK + IMSDK</font></html>。 | ||
| - | ===4、导入SDK=== | ||
| - | 将下载好的IMSDK和TCPSDK文件夹拖入到项目中，并勾选Destination。 | ||
| - | {{ :playground:222.png?nolink |}} | ||
| - | | ||
| - | ===5、添加系统依赖库=== | ||
| - | 向Build Phases -> Link Binary With Libraries 中添加以下依赖库 | ||
| - | {{ :playground:333.png?nolink |}} | ||
| - | |||
| - | SDK的依赖库有: | ||
| - | <code objc> | ||
| - | libstdc++.dylib | ||
| - | libc++.dylib | ||
| - | libz.1.1.3.dylib | ||
| - | SystemConfiguration.framework | ||
| - | libsqlite3.0.dylib | ||
| - | libicucore.dylib | ||
| - | </code> | ||
| - | 如果您使用的是 <html><font color = red>Xcode7.*</font></html> 版本，则需要将上面的动态库<html><font color = red>*.dylib</font></html> 的后缀改为<html><font color = red>*.tdb</font></html>。\\ | ||
| - | ===6、设置ObjC属性=== | ||
| - | 向Targets ->Build Settings -> Linking -> Other Linker Flags 中 添加<html><font color = red>-ObjC</font></html>(注意大小写) | ||
| - | {{ :playground:444.png?nolink |}} | ||
| - | ===7、设置 App 支持 HTTP=== | ||
| - | iOS 9 中，Apple 引入了新特性<html><font color = red> App Transport Security (ATS)</font></html>，默认要求 App 必须使用<html><font color = red> HTTPS </font></html>协议。 | ||
| - | 云之讯IMSDK内部需要使用到 HTTP，所以您需要设置在 App 中使用允许使用 HTTP。 | ||
| - | 在 App 的 Info.plist 中添加NSAppTransportSecurity类型Dictionary。 | ||
| - | 在 NSAppTransportSecurity 下添加 NSAllowsArbitraryLoads类型Boolean，值设为 YES。 | ||
| - | |||
| - | |||
| - | |||
| - | ===== 二、IMSDK 快速集成 ===== | ||
| - | ==== 1、获取TOKEN==== | ||
| - | 云之讯TOKEN分为两类:\\ | ||
| - | 第一类是<html><font color = red>开发者主账号ID（ACCOUNT SID）</font></html>对应的<html><font color = red>AUTH TOKEN</font></html>，相当于开发者账号的密码，在SDK登录、REST请求中使用，您可以在开发者控制台查看这个<html><font color = red>TOKEN</font></html>。初始的开发者TOKEN在网站注册后，系统自动生成；如果出现开发者TOKEN泄露的情况，系统支持开发者TOKEN重置。\\ | ||
| - | 第二类是开发者创建的应用下的<html><font color = red>用户TOKEN</font></html>，相当于您APP上当前用户连接云之讯平台的身份凭证。您可以通过<html><font color = red>REST API</font></html>为您APP上的每一位用户创建一个对应的子账号，您的APP账户体系和云之讯账户体系一一对应。获取到这个TOKEN之后，您APP上的用户就可以使用这个TOKEN去连接云之讯服务器。您可以前往[[http://docs.ucpaas.com/doku.php?id=rest_api%E4%BB%8B%E7%BB%8D%E5%8F%8A%E6%8E%A5%E5%85%A5|Rest API介绍]]了解更多。\\ | ||
| - | |||
| - | ==== 2、工程准备 ==== | ||
| - | 您在尝试集成 SDK 的时候，为了方便，可以新建一个工程。并参考前面章节中的步骤，在工程中导入了SDK并设置了各种库依赖。 | ||
| - | ====3、初始化SDK ==== | ||
| - | 云之讯建议您为您的APP添加一个预编译文件，在这个预编译文件中引入UCSIMSDK头文件和UCSTCPSDK头文件\\ | ||
| - | <code java> | ||
| - | #import "UCSIMSDK.h" | ||
| - | #import "UCSTCPSDK.h" | ||
| - | </code> | ||
| - | |||
| - | ===1、连接服务器 === | ||
| - | 将您获取到的Token，通过UCSTcpClient的单例，传入到<html><font color = red>-login_connect:success:failure:</font></html>方法，即可建立和云之讯服务器的连接。\\ | ||
| - | 在 App 整个生命周期，您只需要调用一次此方法与云之讯服务器建立连接。之后无论是网络出现异常或者 App 有前后台的切换等，TCPSDK都会负责自动重连。TCPSDK针对iOS的前后台和各种网络状况，进行了连接和重连机制的优化，建议您调用一次<html><font color = red>-login_connect:success:failure:</font></html>方法即可，其余交给TCPSDK处理。 除非您已经手动将连接断开,或者其他地方登陆将您强行T下线,否则您不需要自己再手动重连。连接服务器时，在登陆结果未返回之前，请不要主动断开连接或者再次登陆。\\ | ||
| - | <code java> | ||
| - | [[UCSTcpClient sharedTcpClientManager] login_connect:@"您的登陆TOKEN" success:^(NSString *userId) { | ||
| - | NSLog(@"登陆成功。当前登录的用户ID：%@", userId); | ||
| - | } failure:^(UCSError *error) { | ||
| - | //TOKEN不正确。 | ||
| - | //网络故障 | ||
| - | NSLog(@"登陆失败, 错误码%d, 错误说明:%@", error.code, error.description); | ||
| - | }]; | ||
| - | </code> | ||
| - | ===2、设置TCPSDK 和 连接状态监听 === | ||
| - | 您可以实时地监控和云之讯服务器之间的连接状态，实时地根据连接状态调整UI显示，优化用户体验。TCPSDK的<html><font color = red>UCSTCPDelegateBase协议</font></html>声明了一些回调方法。您可以遵守UCSTCPDelegateBase协议，设置TCPSDK的代理对象，并且实现<html><span style="color:red">-didConnectionStatusChanged:error:</span></html>方法来监控连接状态。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * 设置TCPSDK代理对象 | ||
| - | */ | ||
| - | [[UCSTcpClient sharedTcpClientManager] setTcpDelegate:self]; | ||
| - | |||
| - | /** | ||
| - | * 实现协议方法，监听连接状态变化 | ||
| - | * @param connectionStatus 当前连接状态 | ||
| - | * @param error 连接异常的错误类 | ||
| - | */ | ||
| - | - (void)didConnectionStatusChanged:(UCSConnectionStatus)connectionStatus error:(UCSError *)error{ | ||
| - | switch (connectionStatus) { | ||
| - | case UCSConnectionStatus_BeClicked: | ||
| - | NSLog(@"当前账号在其他地方登陆，您被强行T下线"); | ||
| - | break; | ||
| - | case UCSConnectionStatus_ReConnectFail: | ||
| - | NSLog(@"重连失败"); | ||
| - | break; | ||
| - | case UCSConnectionStatus_StartReConnect: | ||
| - | NSLog(@"开始重连"); | ||
| - | break; | ||
| - | case UCSConnectionStatus_ReConnectSuccess: | ||
| - | NSLog(@"重连成功"); | ||
| - | break; | ||
| - | case UCSConnectionStatus_loginSuccess: | ||
| - | NSLog(@"登陆成功"); | ||
| - | break; | ||
| - | case UCSConnectionStatus_ConnectFail: | ||
| - | NSLog(@"登陆失败"); | ||
| - | break; | ||
| - | default: | ||
| - | break; | ||
| - | } | ||
| - | } | ||
| - | </code> | ||
| - | ===3、设置IMSDK代理 === | ||
| - | 当收到新消息、讨论组发生变化时，IMSDK会通过<html><font color = red>UCSIMClientDelegate</font></html>协议通知上层。您需要遵守<html><font color = red>UCSIMClientDelegate</font></html>协议,设置IMSDK的代理对象,实现协议方法才能够监听这些事件。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | *设置IMSDK的代理对象 | ||
| - | */ | ||
| - | [[UCSIMClient sharedIM] setDelegate:self]; | ||
| - | |||
| - | /** | ||
| - | * 收到了消息 | ||
| - | * @param messageArray 消息数组 | ||
| - | */ | ||
| - | - (void)didReceiveMessages:(NSArray *)messageArray{ | ||
| - | NSLog(@"收到了消息"); | ||
| - | } | ||
| - | |||
| - | /** | ||
| - | * 被T出某个讨论组时回调 | ||
| - | * @param discussionID 讨论组id | ||
| - | */ | ||
| - | - (void)didRemoveFromDiscussionWithDiscussionId:(NSString *)discussionID{ | ||
| - | NSLog(@"你被踢出了讨论组 , 讨论组id为: %@", discussionID); | ||
| - | } | ||
| - | </code> | ||
| - | |||
| - | ===4、断开连接 === | ||
| - | 当您需要与云之讯服务器断开连接时，您可以通过<html><font color = red>UCSTcpClient</font></html>的单例，调用<html><font color = red>login_uninitWithFlag:</font></html>方法。在断开与云之讯服务器的连接时，您可以设置是否仍接收远程推送。\\ | ||
| - | 如果设置了接收推送，断开连接之后，如果有人给该用户 ID 发送消息，云之讯的服务器会根据<html><font color = red> DeviceToken</font></html> 和<html><font color = red>推送证书</font></html>将消息发送到苹果推送服务器，苹果服务器会将该消息以远程推送的形式下发到客户端。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 断开客户端和云平台的连接,并且根据flag标识的bool值选择是否关闭离线推送。 | ||
| - | * @param flag 是否关闭推送的bool值。YES，关闭。NO，不关闭。 | ||
| - | * @discussion 断开连接。 | ||
| - | */ | ||
| - | - (void)login_uninitWithFlag:(BOOL)flag; | ||
| - | </code> | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | ===== 三、会话 ===== | ||
| - | 会话实体类UCSConversation，每一个UCSConversation对象代表本地存储的一条会话。UCSConversation包含以下属性:<html><font color = red>会话类型(conversationType)、会话ID(targetId)、会话名称(conversationTitle)、未读消息数(unreadMessageCount)、是否置顶(isTop)、草稿(draft)、最近一条消息相关(receivedStatus、sentStatus、time、senderUserId、senderUserName、lastestMessageType、lastestMessageId、lastestMessage)</font></html>。\\ | ||
| - | ==== 1、查询本地存储的会话 ==== | ||
| - | <code java> | ||
| - | |||
| - | /** | ||
| - | * @brief 获取会话列表 | ||
| - | * @param conversationListType 会话列表的类型。具体参考UCS_IM_ConversationListType | ||
| - | * @return 会话数组，每个元素是一个UCSConversation对象 | ||
| - | */ | ||
| - | - (NSArray *)getConversationList:(UCS_IM_ConversationListType)conversationListType; | ||
| - | |||
| - | </code> | ||
| - | ==== 2、删除本地存储的会话 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 清空会话列表 | ||
| - | * @discussion 这个方法是用来清空会话列表，注意和clearMessages:targetId:这个方法区分开来。 | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)clearConversations; | ||
| - | |||
| - | /** | ||
| - | * @brief 在会话列表中移除一个会话，但是不会删除该会话在数据库中的消息。 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)removeConversation:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | </code> | ||
| - | ==== 3、置顶会话 ==== | ||
| - | 对一些关键会话，您可以选择性地将会话置顶或者取消置顶。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 会话列表中,设置某条会话的置顶状态 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param isTop YES 置顶 , NO 取消置顶 | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)setConversationToTop:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | isTop:(BOOL)isTop; | ||
| - | </code> | ||
| - | |||
| - | ==== 4、会话的草稿 ==== | ||
| - | 您可以将用户保留在输入框未发出去的消息保存起来,当用户进入同一会话的聊天界面时填充在输入框中,优化用户体验。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 获取某个会话的文本草稿 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @return 文本草稿。如果没有，为空。 | ||
| - | */ | ||
| - | - (NSString *)getTextMessageDraft:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 保存某个会话的文本草稿 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param content 文本草稿 | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)saveTextMessageDraft:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | content:(NSString *)content; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 清除某个会话的文本草稿 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)clearTextMessageDraft:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | </code> | ||
| - | ==== 5、会话的未读消息数 ==== | ||
| - | 您可以获取单个会话的未读消息或者全部会话的未读消息总数，显示给用户，提醒用户去查看对应的消息。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 获取某个会话的未读消息数 | ||
| - | * @discussion 这个方法用来获取某个会话的未读消息数，提醒用户有未读的消息.(如果传入的参数错误或者操作获取失败,会返回-1) | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @return 未读消息数量.(注意:如果传入的参数错误，则直接返回-1) | ||
| - | */ | ||
| - | - (NSInteger)getUnreadCount:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 获取所有会话的未读消息总数 | ||
| - | * @return 未读消息总数 | ||
| - | */ | ||
| - | - (NSInteger)getTotalUnreadCount; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 清空某个会话的未读消息总数 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)clearConversationsUnreadCount:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | </code> | ||
| - | ==== 6、会话的消息 ==== | ||
| - | 您可以在聊天界面加载完成之后,调用下面的方法加载历史消息记录，展示给用户。暂时只能获取本地存储的消息，无法获取服务器存储的消息。\\ | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 获取最新的消息.用于进入聊天界面后第一次加载消息 | ||
| - | * @discussion 这个方法用于进入聊天界面第一次加载消息时候调用,如果下拉加载更多消息的时候请使用下面的 -getLatestMessages:targetId:count: 方法 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param count 需要获取的消息数量。默认获取20条。也可以自己设置,如果该会话的消息总数小于设置的count数，则返回该会话的消息总数。 | ||
| - | * @return 消息数组。数组中元素的类型是UCSMessage | ||
| - | */ | ||
| - | - (NSArray *)getLatestMessages:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | count:(int)count; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 获取更多的消息。用于聊天界面中加载更多消息。 | ||
| - | * @discussion 这个方法用于聊天界面中下拉加载更多消息时候调用。进入聊天界面第一次加载消息请使用上面的 - getLatestMessages:targetId:count: 方法。 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param oldestMessageId 当前已经请求好的消息中最早的那条消息的消息id。 | ||
| - | * @param count 需要获取的消息数量 | ||
| - | * @return 消息数组 | ||
| - | */ | ||
| - | - (NSArray *)getHistoryMessages:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | oldestMessageId:(long long)oldestMessageId | ||
| - | count:(int)count; | ||
| - | </code> | ||
| - | ===== 四、消息 ====== | ||
| - | ==== 1、发送消息 ==== | ||
| - | 您可以调用<html><font color = red>-sendMessage:receiveId:msgType:content:success:failure:</font></html>方法来发送一条聊天消息。SDK所有的消息发送都使用这个方法，根据不同的参数来区分不同的消息类型。 | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 发送一条聊天消息 | ||
| - | * @discussion SDK所有的消息发送都使用这个方法，根据不同的参数来区分不同的消息类型。 | ||
| - | * @param conversationType 这条消息对应的会话的类型。这个参数用来区分这条消息是什么场景下产生的。现在暂时有单聊、群聊、讨论组三中会话类型。比如一对一单聊,设为UCS_IM_SOLOCHAT。具体参考UCS_IM_ConversationType | ||
| - | * @param receiveId 聊天对象的id。这个参数用来标识这条消息发到哪里,单聊发给某个人,群聊发给某个讨论组或者某个群。单聊设置为对方的id,讨论组设置为讨论组id,群聊设置为群id。 | ||
| - | * @param msgType 消息的类型。这个参数用来标识这条消息的类型。比如文本消息，设置为UCS_IM_TEXT。具体参考UCS_IM_MsgType | ||
| - | * @param content 消息实体。这个参数存储发送的内容。UCSMsgContent是一个消息基类，这里传入一个继承UCSMsgContent的子类的对象。比如发送文本消息时，传入UCSTextMsg类型的对象。注意:这里传的内容对象的类型必须和前一个参数msgType类型对应。比如不允许前一个参数传文本类型，后一个参数传图片，否知会出现错误。当传文本消息的时候，文本的长度不要超过1500,否则视为参数错误。当传入图片消息时,单张图片的字节流大小不要超过20M。 | ||
| - | * @param success 发送消息成功的Block回调。回调中会返回发送成功的消息id,拿到这个id可以做一些自定义的处理。比如刷新消息的发送状态。 | ||
| - | * @param failure 发送消息失败的Block回调。回调中会返回发送失败的消息id和发送失败的错误对象，自定义处理。 | ||
| - | * @return 发送的message。此时消息的发送状态为发送中，需要根据success回调和failure回调来改变消息的发送状态。(注意:如果发送的参数不符合要求，会回调失败。发送的文本长度不能超过1500。当发送语音消息时，语音大小不要超120kB，否则会丢失部分语音内容) | ||
| - | */ | ||
| - | - (UCSMessage *)sendMessage:(UCS_IM_ConversationType)conversationType | ||
| - | receiveId:(NSString *)receiveId | ||
| - | msgType:(UCS_IM_MsgType)msgType | ||
| - | content:(UCSMsgContent *)content | ||
| - | success:(void (^)(long long messageId))success | ||
| - | failure:(void (^)(UCSError *error, long long messageId))failure; | ||
| - | </code> | ||
| - | ==== 2、删除消息==== | ||
| - | 您可以调用<html><font color = red>-deleteMessages:targetId:messageId:</font></html>方法来删除一条聊天消息。被删除的聊天消息将会在数据库中彻底删除。 | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 删除一条指定的消息 | ||
| - | * @discussion 这个方法一般用于聊天界面删除一条消息，删除后这条消息在数据库中也会被删除。 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param messageId 消息id | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)deleteMessages:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | messageId:(long long)messageId; | ||
| - | </code> | ||
| - | |||
| - | 您也可以删除某个会话的所有消息 | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 清空某一个会话所有的聊天记录 | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id。 | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | - (BOOL)clearMessages:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId; | ||
| - | </code> | ||
| - | ==== 3、修改消息的接收状态 ==== | ||
| - | 您可以调用<html><font color = red>-setMessageReceivedStatus:targetId:messageId:receivedStatus:</font></html>方法来修改消息在数据中的接收状态。 | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 设置接收到的某条消息在本地的接收状态。具体参考UCSReceivedStatus | ||
| - | * @param conversationType 会话类型。类型值参考UCS_IM_ConversationType | ||
| - | * @param targetId 会话id。单聊为对方的id，讨论组聊天为讨论组id，群组聊天为群组id | ||
| - | * @param messageId 消息id。 | ||
| - | * @param receivedStatus 要设置的状态。类型值参考UCSReceivedStatus | ||
| - | * @return 操作结果的bool值 | ||
| - | */ | ||
| - | -(BOOL)setMessageReceivedStatus:(UCS_IM_ConversationType)conversationType | ||
| - | targetId:(NSString *)targetId | ||
| - | messageId:(long long)messageId | ||
| - | receivedStatus:(UCSReceivedStatus)receivedStatus; | ||
| - | </code> | ||
| - | ===== 五、讨论组 ====== | ||
| - | 讨论组是用户创建的多人聊天室，SDK提供了讨论组创建、加人、踢人、设置、退出、查询等功能。讨论组的创建者将默认为该讨论组的管理员，当管理员退出讨论组后，将重新分配讨论组管理员。 | ||
| - | ==== 1、创建讨论组 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 主动创建一个讨论组 | ||
| - | * @discussion 这个方法用来主动创建一个讨论组。成功block回调返回一个讨论组,失败block回调返回错误码。创建成功后，创建者会自动变成讨论组的所有者，拥有对讨论组操作的最高权限。 | ||
| - | * @param topic 创建后的讨论组主题(讨论组名),不能为nil。 | ||
| - | * @param memberArray 创建时需要邀请到讨论组的成员数组(不需要把自己加进去),数组中每个元素为UCSUserInfo类的对象。加入到这个成员数组的每个成员必须保证是已经在云平台注册的成员，否则会失败。 | ||
| - | * @param success 创建成功。block回调返回创建成功的讨论组 | ||
| - | * @param failure 创建失败。block回调返回错误对象。 | ||
| - | */ | ||
| - | - (void)createDiscussionWithTopic:(NSString *)topic | ||
| - | memberArray:(NSArray *)memberArray | ||
| - | success:(void (^)(UCSDiscussion *discussion))success | ||
| - | failure:(void (^)(UCSError *error))failure; | ||
| - | </code> | ||
| - | ==== 2、加人 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 给已经存在的讨论组添加新的用户 | ||
| - | * @discussion 这个方法用来给一个已经存在的讨论组添加新的成员，如果用户无权限进行操作会失败。 | ||
| - | * @param discussionId 讨论组id | ||
| - | * @param memberArray 要新加的成员的数组，数组中的每个元素为UCSUserInfo类的对象。 | ||
| - | * @param success 添加成功.回调中返回修改后的讨论组 | ||
| - | * @param failure 添加失败.回调中返回错误对象 | ||
| - | */ | ||
| - | - (void)addMemberToDiscussionWithDiscussionId:(NSString *)discussionId | ||
| - | memberArray:(NSArray *)memberArray | ||
| - | success:(void (^)(UCSDiscussion *discussion))success | ||
| - | failure:(void (^)(UCSError *error))failure; | ||
| - | </code> | ||
| - | ====3、踢人 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 在讨论组中移除已经存在的用户 | ||
| - | * @discussion 这个方法用来删除一个存在的讨论组中存在的成员,如果用户无权限进行操作会失败。 | ||
| - | * @param discussionId 讨论组id | ||
| - | * @param memberArray 要移除的用户的数组，数组中的每个元素为UCSUserInfo类的对象。 | ||
| - | * @param success 移除成功.回调中返回修改后的讨论组 | ||
| - | * @param failure 移除失败.回调中返回错误对象 | ||
| - | */ | ||
| - | - (void)removeMemberFromDiscussionWithDiscussionId:(NSString *)discussionId | ||
| - | memberArray:(NSArray *)memberArray | ||
| - | success:(void (^)(UCSDiscussion *discussion))success | ||
| - | failure:(void (^)(UCSError *error))failure; | ||
| - | </code> | ||
| - | ==== 4、设置 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 修改讨论组的主题(讨论组名称) | ||
| - | * @param discussionId 讨论组id | ||
| - | * @param newTopic 新的主题 | ||
| - | * @param success 修改成功。回调中返回修改后的讨论组。 | ||
| - | * @param failure 修改失败。回调中返回失败的错误对象 | ||
| - | */ | ||
| - | - (void)setDiscussionTopicWithDiscussionId:(NSString *)discussionId | ||
| - | newTopic:(NSString *)newTopic | ||
| - | success:(void (^)(UCSDiscussion *discussion))success | ||
| - | failure:(void (^)(UCSError *error))failure; | ||
| - | </code> | ||
| - | ==== 5、退出 ==== | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 主动退出讨论组 | ||
| - | * @param discussionId 讨论组id | ||
| - | * @param success 退出成功 | ||
| - | * @param failure 退出失败。回调中返回错误对象 | ||
| - | */ | ||
| - | - (void)quitDiscussionWithDiscussionId:(NSString *)discussionId | ||
| - | success:(void (^)(UCSDiscussion *discussion))success | ||
| - | failure:(void (^)(UCSError *error))failure; | ||
| - | </code> | ||
| - | |||
| - | ==== 6、查询 ==== | ||
| - | 您可以查询自己当前加入的所有讨论组，或者查询当前加入的某一个讨论组。 | ||
| - | <code java> | ||
| - | /** | ||
| - | * @brief 获取一个存在的讨论组。如果本地不存在这个讨论组的信息，就会返回空。 | ||
| - | * @param targetId 讨论组id | ||
| - | * @return 讨论组。 | ||
| - | */ | ||
| - | - (UCSDiscussion *)getDiscussionInfoWithDiscussionId:(NSString *)targetId; | ||
| - | |||
| - | |||
| - | /** | ||
| - | * @brief 获取当前账号加入的所有讨论组，返回一个数组，其中的每个元素是一个UCSDiscussion类型的对象 | ||
| - | * @return 返回加入的所有讨论组.如果当前账号没有加入任何讨论组，则数组为空。 | ||
| - | */ | ||
| - | - (NSArray *)getDiscussions; | ||
| - | </code> | ||
| - | ===== 六、群组 ====== | ||
| - | 群组关系和群组列表由您的 App 维护，客户端的所有群组操作都需要请求您的 <html><font color = red>App Server</font></html>， 您的 <html><font color = red>App Server</font></html> 可以根据自己的逻辑进行管理和控制，然后通过 <html><font color = red>Server API</font></html> 接口进行群组操作，并将结果返回给客户端。\\ | ||
| - | |||
| - | |||
| - | 如果您想了解更多,请前往[[http://172.16.5.37:1122/doku.php?id=im_%E6%9C%8D%E5%8A%A1%E7%AB%AF%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#dokuwiki_header|IM服务端开发文档]]。\\ | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
