====== Android SDK集成 ====== 本篇文档旨在帮助开发者快速集成Android SDK，开发者在阅读文档之前需具备一定的Android开发基础知识。 ===== 一、前期准备 ===== ==== 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& }}\\ 您可以点击页面左上方创建应用按钮开始创建一个应用。在创建应用界面，您需要填写应用名称、应用类型、所属行业三个必选项。云之讯强烈建议您设置服务器白名单，设定白名单地址后，云之讯服务器在识别该应用请求时将只接收白名单内服务器发送的请求，能有效提升帐号安全性。如未设置默认不生效。如果您的应用需要使用到高级配置中的能力，您需要勾选对应的能力项。\\ {{ :云之讯控制台_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 SDK，您可以通过[[http://www.ucpaas.com/product_service/im|云之讯官网]]下载IM SDK。压缩包中分为三部分：\\ * 1) IM核心功能 jar包：yunzhixun_IM_SDK_ver_x.x.x_release.jar * 2) TCP连接jar包：yunzhixun_TCP_SDK_ver_x.x.x_release.jar * 3) 传输协议处理库：libpack.so、libcrypto.so（放入armeabi文件夹下） ===== 二、快速集成 ===== ==== 1、创建项目 ==== 如果您还未创建应用，那么请您先创建一个空项目来导入云之讯IM SDK。这里我们以Eclipse为例，后面的操作也是如此。\\ 如图我们创建了一个名为MyApp的空项目： {{ :im_sdk_my_app_01.png?nolink& }} ==== 2、导入SDK ==== 将您下载好的SDK拷贝到正确的位置，放置好的效果如下图所示： {{ :im_sdk_src_libs.png?nolink& }} ==== 3、添加配置 ==== 将下列权限添加到AndroidManifest.xml文件中

将下列服务和广播的声明添加到AndroidManifest.xml文件中

==== 4、初始化 ==== 初始化操作旨在启动IM服务，传递上下文对象传递给sdk。为了您能够继续进行下面的步骤，请您一定要在应用创建的时候初始化，云之讯提供以下两种方法供参考：\\ **方法1：** 新建MainApplication继承自sdk里面已经定义好的IMApplication，IMApplication里面自动帮您完成了初始化工作，具体参考如下：


public class MainApplication extends IMApplication {
    @Override
    public void onCreate() {
        super.onCreate();
    }
}

**方法2：** 如果您不想使用云之讯IMApplication，您可以新建MainApplication继承自系统的Application，并在应用创建的时候初始化，具体参考如下：


public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        /**
         * 启动IM核心服务
         */
        UCSManager.init(this);
        /**
         * 传递上下文对象给SDK
         */
        IMManager.getInstance(this);
    }
}

===== 三、连接云平台 ===== ==== 1、流程说明 ==== 云之讯认为，每位开发者在调用sdk连接云平台之前，需要熟悉登录的每个细节。\\ 对于开发者的app用户来讲，userId才是app用户需要关心的内容，开发者app Server应该使用userId唯一标识每个用户；对于云之讯后台服务器来讲，是使用token唯一标识每个用户。\\ 当app用户输入userId开始登录的时候，app应该请求App Server查找与该userId对应的token。这里存在两种情况：\\ * 1) 如果app Server查找token成功(该userId已经注册)，则将对应的token返回给app，app将返回的Token传入sdk的connect方法连接云平台。 * 2) 如果app Server查找token失败(该userId未注册)，app Server应该调用云之讯server API注册当该用户，并将云之讯后台返回的token和userId一一对应起来保存，方便app用户下次继续获取token。最后将对应的token返回给app，app将返回的token传入sdk的connect方法连接云平台。用户未注册流程： {{ :android_not_register.png?nolink&680 }}\\ 用户已注册流程： {{ :android_has_register.png?nolink&520 }}\\ 这里有两点需要注意的地方：\\ * 1) app Server：指的是开发者后台服务器 * 2) app用户：指的是使用开发者应用的用户 ==== 2、获取Token ==== 登录流程里面已经进行过说明，云之讯后台服务器是通过Token唯一标识一个app用户。开发者在连接服务器之前，需要将app用户输入的userId提交到App Server，获取到与userId对应的Token。App Server获取Token的方法请参考[[http://docs.ucpaas.com/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|IM服务端开发文档]]。 ==== 3、连接服务器 ==== 在链接服务器之前，请您确认已经通过server Api获取到token，并将获取到的token传入connect方法，开始连接服务器。一般来讲，连接服务器操作成功(失败情况下sdk不会重连)后用户无需再调用连接操作，sdk内部会根据实际情况进行重连。如果连接服务器成功后，您手动调用了断开操作，那么sdk将不会重连。\\ 云之讯为开发者提供UCSManager控制类，用来完成连接服务器操作。


/**
 * 连接云平台
 * 
 * @param token 用户token
 */
public void connect(token, new ILoginListener() {
  @Override
  public void onLogin(UcsReason reason) {
    if(reason.getReason() == UcsErrorCode.NET_ERROR_CONNECTOK){
      Log.d("YZX", "login success");
    }else{
      Log.d("YZX", "login fail errorCode = "+reason.getReason()+",errorMsg = "+reason.getMsg());
    }
  }
});

===== 四、会话 ===== 会话ConversationInfo是用来描述保存到本地数据库中会话信息的实体类，通过targetId(会话id)来唯一标识一个会话。会话的属性分别有不同的用处，categoryId(标识会话的类型，如：单聊、群聊、讨论组)，isTop(是否置顶)，msgUnRead(未读消息数)等等，这些属性都可以通过ConversationInfo的get方法得到。 ==== 1、获取会话 ==== 云之讯提供IMManager控制类进行获取会话操作。


/**
 * 获取会话列表。
 *
 * 默认按照lastTime(最后一条消息的时间)降序排序，简单来说就是，新消息在最前面。
 * 置顶的会话会在最前面，如果有多个置顶会话，这些置顶会话也是按照按照lastTime(最后一条消息的时间)降序排序。
 * @return            获取到的会话列表集合。
 */
public List getConversationList()
/**
 * 获取指定categroyId(会话类型)的会话列表。
 *
 * 默认按照lastTime(最后一条消息的时间)降序排序，简单来说就是，新消息在最前面。
 * 置顶的会话会在最前面，如果有多个置顶会话，这些置顶会话也是按照按照lastTime(最后一条消息的时间)降序排序。
 * @param  categroyId 会话类型(单聊，群聊，讨论组)。
 * @return            指定categroyId(会话类型)的会话列表。
 */
public List getConversationList(CategoryId categroyId)
/**
 * 获取指定targetId(会话id)的会话。
 *
 * @param  targetId  会话id。
 * @return           如果存在，则返回该targetId的会话，否则返回Null。
 */
public ConversationInfo getConversation(String targetId)

==== 2、删除会话 ==== 云之讯提供IMManager控制类进行删除会话操作。


/**
 * 清空所有会话。
 *
 * @return 清空的会话数。
 */
public int clearAllConversations()
/**
 * 删除数据库中指定的会话记录。
 *
 * @param  cinfo 要删除的会话对象。
 * @return       0表示删除该会话失败，大于0表示删除该会话成功。
 */
public int delConversationInfo(ConversationInfo cinfo)

==== 3、会话置顶 ==== 会话置顶由会话类本身进行操作


/**
 * 设置某一会话为置顶或者取消置顶。
 *
 * @param isTop true表示置顶，false表示取消置顶。
 */
public void setIsTop(boolean isTop)

==== 4、会话草稿 ==== 会话草稿由会话类本身进行操作。


/**
 * 获取该会话的草稿。
 *
 * 会话草稿一般用到会话列表页面，显示每条会话的最后内容。
 * 默认情况下，SDK会将当前会话的最后一条消息内容设置为草稿。
 * 如果最后一条消息为文本消息，SDK默认设置的草稿就是该文本内容。
 * 如果最后一条消息为语音消息，SDK默认设置的草稿格式为"[语音:xx秒]"。
 * 如果最后一条消息为图片消息，SDK默认设置的草稿格式为"[图片]"。
 * 如果最后一条消息为地图消息，SDK默认设置的草稿格式为"[地图]"。
 * 如果最后一条消息为自定义消息，SDK默认设置的草稿格式为"[自定义消息]"。
 * @return 该会话草稿内容。
 */
public String getDraftMsg()
/**
 * 为该会话设置草稿。
 *
 * 默认情况下用户不需要设置草稿内容，sdk收到消息的时候会更新草稿内容。
 * 设置草稿一般用在聊天页面，用户输入聊天内容后没有发送，这个时候开发者可以手动设置草稿，方便在会话列表页面显示。
 * 这里需要注意的是：开发者在删除当前会话的某些消息时，SDK不会更新草稿内容，这个时候开发者也是需要手动设置草稿，一般来说是设置为最后一条消息的消息内容。
 * @param draftMsg 要设置的草稿内容。
 */
public void setDraftMsg(String draftMsg)

==== 5、会话未读消息 ==== 会话未读消息数可以由会话本身获取，也可以调用IMManager操作类获取，下面以IMManager为例进行说明：


/**
 * 获取所有会话的未读消息数总和。
 *
 * @return 所有会话未读消息数的总和。
 */
public int getUnreadCountAll()
/**
 * 获取指定会话的未读消息数总和。
 *
 * 该会话当收到新消息时，该会话的未读消息数会自动增加。
 * @param cinfo 要指定的会话对象。
 * @return      指定会话未读消息数的总和。
 */
public int getUnreadCount(ConversationInfo cinfo)
/**
 * 清除当前会话的未读消息状态。
 *
 * 调用该方法后，getUnreadCount()将返回0条未读消息数。
 * 开发者应该在用户查看完当前会话之后，调用该方法清除当前会话的未读消息。
 */
public void clearMessagesUnreadStatus()

===== 五、消息 ===== 消息ChatMessage是描述本地数据库中消息信息的实体类，其中包含了所有与消息有关的信息。属性有：targetId(接收方id)、categoryId(消息分类)、msgType(消息类型)、content(消息内容)等等。\\ 消息ChatMessage如果以会话来分的话，消息可以分为SingleChat(单聊消息)、DiscussionChat(讨论组消息)、GroupChat(群聊消息)。如果以MSGTYPE(消息类型)来分，可以分为：文本消息、语音消息、图片消息、地图消息、自定义消息。 ==== 1、发送消息 ==== 云之讯提供IMManager控制类，用来发送消息。


/**
 * 发送一条消息。
 *
 * @param  msg  要发送的消息对象，发送消息后会自动将消息入库。
 * @return      发送消息是否成功。
 */
public boolean sendmessage(ChatMessage msg)


/**
 * 获取当前会话指定索引的消息列表。
 *
 * @param startPos     从最新消息开始索引，0表示最新，依次递增消息越早。
 * @param count        要获取的消息数量。
 * @return             查询到的消息列表。
 */
public List getLastestMessages(int startPos, int count)
/**
 * 获取当前会话指定索引的消息列表。
 *
 * @param startPos     从最早消息开始索引，0表示最早，依次递增消息越新。
 * @param count        要获取的消息数量。
 * @return             查询到的消息列表。
 */
public List getHistroyMessages(int startPos, int count)
/**
 * 获取当前会话所有消息。
 *
 * @return             查询到的消息列表。
 */
public List getAllMessage()
/**
 * 获取当前会话指定消息id的消息。
 *
 * @param msgId        指定的消息id。
 * @return             查询到的消息。
 */
public ChatMessage getMessageFromMsgid(String msgId)

==== 3、删除消息 ==== 云之讯提供IMManager控制类指定的ConversationInfo(会话)删除消息，当前开发者也可以直接通过ConversationInfo(会话)删除消息，下面以ConversationInfo删除消息为例：\\


/**
 * 清空当前会话所有消息。
 * 
 * 该会话的所有语言文件、图片文件也会一起删除。
 * @return             清空结果，false表示清空失败，true表示清空成功。
 */
public boolean clearMessages()
/**
 * 删除当前会话指定的消息。
 *
 * @param msgs         要删除的消息列表。
 * @return             删除结果，false表示删除失败，true表示删除成功。
 */
public boolean deleteMessages(List msgs)

===== 六、讨论组 ===== 讨论组是指临时讨论某个共同话题产生的多人聊天，用户对讨论组的操作不受权限的控制，用户可以随意完成创建、踢人、拉人、修改、退出等操作。这里需要注意的是，讨论组创建者默认为该讨论组的管理员，只有管理员才有踢人的权限，当管理员退出后，将重新分配讨论组管理员。云之讯提供IMManager控制类对讨论组进行操作。\\ 云之讯用讨论组id来唯一标识讨论组，创建讨论组成功后，云之讯会为该讨论组分配讨论组id，并将讨论组保存到本地数据库，后续的踢人、拉人、修改、退出等操作也将使用讨论组id来标识，同时云之讯用userId来标识讨论组成员。 ==== 1、创建讨论组 ====


/**
 * 创建讨论组。
 *
 * 创建讨论组成功后，云之讯会为该讨论组分配id。
 * @param name       讨论组名称，如：当前所有成员的名字的组合。
 * @param memberList 讨论组成员 Id 列表，请开发者保证所有的成员都是已经注册过，否则创建讨论组会失败。
 * @return           传入的参数是否合法，参数不合法如：name为空，memberList为空或者size<1，参数不合法将返回false，参数合法返回true。
 */
public boolean createDiscussionGroup(String name,List memberList)

==== 2、退出讨论组 ====


/**
 * 退出讨论组。
 *
 * @param id         指定要退出的讨论组id，请开发者保证该讨论组是创建过的，否则退出讨论组将失败。
 * @return           如果id为空，将返回false,否则返回true。
 */
public boolean quitDiscussionGroup(String id)

==== 3、加人 ====


/**
 * 邀请成员加入讨论组。
 *
 * @param id         讨论组id，请开发者确保该讨论组已经被创建过。
 * @param memberList 需要邀请的讨论组成员 Id 列表，请开发者保证所有要邀请的成员都是已经注册过，否则加入讨论组会失败。
 * @param            传入的参数是否合法，参数不合法如：name为空，memberList为空或者size<1，参数不合法将返回false，参数合法返回true。
 */
public boolean addDiscussionGroupMember(String id,List memberList)

==== 4、踢人 ====


/**
 * 踢出讨论组指定的成员。
 *
 * @param id         讨论组id，请开发者确保该讨论组已经被创建过。
 * @param memberList 需要退出的讨论组成员 id 列表，请开发者保证传入的id是指定的讨论组成员的id。
 * @param            传入的参数是否合法，参数不合法如：name为空，memberList为空或者size<1，参数不合法将返回false，参数合法返回true。
 */
public boolean delDiscussionGroupMember(String id,List memberList)

==== 5、修改 ====


/**
 * 修改指定讨论组的名称。
 *
 * @param id         讨论组id，请开发者确保该讨论组已经被创建过。
 * @param name       修改后的讨论组名称，不能为空。
 * @param            传入的参数是否合法，参数不合法如：name、id为空，参数不合法将返回false，参数合法返回true。
 */
public boolean modifyDiscussionTitle(String id, String name)

==== 6、获取 ====


/**
 * 获取本地数据库中所有的讨论组记录。
 *
 * @return           获取到的讨论组集合。
 */
public List getAllDiscussionInfos()

===== 七、群组 ===== 群组是具有相同爱好和共同话题的用户聚集在一起产生的群体，云之讯既不维护也不保存开发者的群组关系，开发者需要调用云之讯\\ server Api完成创建群组、解散群组、加入群组等操作，具体操作请参考[[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服务端开发文档]]。\\ 以下是群组操作的流程图：\\ ==== 1、创建群组 ==== {{ :create_groupvsdx.png?nolink&680 |}} ==== 2、更新群组 ==== {{ :update_groupvsdx.png?nolink&680 |}} ==== 3、加入群组 ==== {{ :join_groupvsdx.png?nolink&680 |}} ==== 4、获取群组列表 ==== {{ :query_groupvsdx.png?nolink&680 |}} ==== 5、退出群组 ==== {{ :quit_groupvsdx.png?nolink&680 |}} ==== 6、解散群组 ==== {{ :dismiss_groupvsdx.png?nolink&680 |}} ===== 八、断开连接 ===== 断开与云之讯连接之后，开发者将不会收到消息提醒，同时云之讯sdk不会自动重连。云之讯为开发者提供UCSManager控制类，用来断开与云之讯的连接。


/**
 * 断开连接(断开后将不会收到新消息)。
 */
public void disconnect()