====== Android UiKit集成 ====== 本篇文档旨在帮助开发者快速集成云之讯android UI组件，云之讯IM UIKit是在原子sdk的基础上封装了IM相关的上层业务和UI，开发者无须处理复杂IM业务及UI，只需启动已封装好的界面就能拥有IM功能。包括：IM会话列表界面、好友列表界面、聊天界面等。\\ 云之讯提供UCS_IMUIManager控制类方便开发者调用，所有的对外接口都以静态函数的形式供开发者使用。 ===== 一、前期准备 ===== ==== 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 ==== 如果您还未下载uiKitSDK，您可以通过[[http://www.ucpaas.com/product_service/im|云之讯官网]]下载uiKit SDK，压缩包中分为两部分：\\ * 1) libs目录：uiKit sdk依赖的jar包和动态库(.so文件) * 2) res文件夹目录：uiKit sdk依赖的资源文件，为了避免和开发者的资源冲突，uiKit sdk的资源文件都以yzx开头。 ===== 二、集成环境 ===== ==== 1、创建项目 ==== 如果您还未创建应用，那么请您先创建一个空项目来导入云之讯IM SDK。这里我们以Eclipse为例，后面的操作也是如此。\\ 如图我们创建了一个名为MyApp的空项目： {{ :im_sdk_my_app_01.png?nolink& }} ==== 2、导入SDK ==== 将压缩包里面的libs和res文件夹拷贝到自己工程与之对应的目录，放置好的效果如下图所示： {{ :im_sdk_src_libs.png?nolink& }} ==== 3、添加配置 ==== 将下列权限添加到AndroidManifest.xml文件中

将百度地图key和value声明添加到AndroidManifest.xml文件中

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

将下列Activity的声明添加到AndroidManifest.xml文件中

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


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

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


public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        /**
         * 初始化sdk
         */
        UCS_IMUIManager.init(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将不会重连。\\


/**
 * 连接云平台。
 * 
 * @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());
    }
  }
});

===== 四、功能集成 ===== 云之讯对外只提供会话列表、聊天、好友列表三个页面。再启动页面之前，请确保已经连接上服务器，并且页面已经配置完毕。 ==== 1、会话列表 ==== 会话列表页面是所有会话的集中地，云之讯会自动更新页面上的内容包括：未读消息数、会话最后消息时间、会话排序等。


/**
 * 启动会话列表界面
 *
 * 开发者应该将当前登录的账号和昵称传递给user对象的userId和nickName属性，并将user对象返回。
 * @param context            应用上下文。
 * @param UCSTransContent    启动参数回调(sdk回调requestUser方法，获取开发者传入的参数)。
 */
UCS_IMUIManager.startIMChatActivity(context,new UCSTransContent() {
  @Override
  public UCSUser requestUser(UCSUser user) {
    /**
     * 将当前登录账号的userId赋值给user.userId
     */
    user.userId = "userId";
    /**
     * 将当前登录账号的昵称赋值给user.nickName
     */
    user.nickName = "昵称";
    /**
     * 返回user给sdk，如果返回null，将启动失败
     */
    return user;
  }
});

效果图如下： {{ :android_conversationinfo_03.png?nolink&280 |}} ==== 2、聊天页面 ==== 聊天页面是用户之间交互的页面，聊天页面可以实现发送文字、语音、图片、位置信息等内容。


/**
 * 启动聊天页面
 *
 * @param context             应用上下文。
 * @param ChatTransContent    启动参数回调(sdk回调requestUser方法，获取开发者传入的参数)。
 */
UCS_IMUIManager.startIMMsgActivity(context,new ChatTransContent() {
  @Override
  public UCSUser requestUser(UCSUser user) {
         /**
          * 将当前登录账号的userId赋值给user.userId
          */
         user.userId = "userId";
         /**
          * 将当前登录账号的昵称赋值给user.nickName
          */
         user.nickName = "昵称";
         /**
          * 返回user给sdk，如果返回null，将启动失败
          */
         return user;
  }
  @Override
  public UCSConversation requestConversation(UCSConversation conversation) {
         /**
          * 聊天对象的id，如：
          * userId(用户id)
          * groupId（群组id)
          * discussionId（讨论组id）
          */
         conversation.targetId = targetID;
         /**
          * 聊天页面Title，如果为null，title默认为targetId 
          */
         conversation.title = "";
         /**
          * 聊天页面类型，如：
          * UCSConversation.PRIVATECHAT(单聊)
          * UCSConversation.GROUPCHAT(群聊)
          * UCSConversation.DISCUSSIONCHAT(讨论组)
          */
         conversation.type = UCSConversation.PRIVATECHAT;
         /**
          * 返回conversation给sdk，如果返回null，将启动失败
          */
         return conversation;
  }
})

效果图如下： {{ :android_chat_02.png?nolink&280 |}} ==== 3、好友列表 ==== 云之讯的好友列表页面每个好友条目前面都会有一个CheckBox，方便开发者将好友拉进讨论组。用户必须手动调用云之讯的设置好友接口之后，好友列表页面才能显示出好友列表信息。


UCS_IMUIManager.startIMFriendListActivity(context,new UCSTransContent() {
  @Override
  public UCSUser requestUser(UCSUser user) {
    /**
     * 将当前登录账号的userId赋值给user.userId
     */
    user.userId = "userId";
    /**
     * 将当前登录账号的昵称赋值给user.nickName
     */
    user.nickName = "昵称";
    /**
     * 返回user给sdk，如果返回null，将启动失败
     */
    return user;
  }
});

效果图如下： {{ :android_discussinfo.png?nolink&280 |}} ===== 五、自定义 ===== 云之讯sdk为开发者提供丰富的自定义功能，开发者可以调用相应的接口轻松完成自定义的效果。云之讯sdk提供的自定义包括：标题栏自定义、好友列表自定义、群组列表自定义、消息通知自定义。 ==== 1、设置标题栏风格 ==== 云之讯sdk默认的标题栏风格为绿色，开发者需要在页面启动前设置标题栏风格才有效果。云之讯sdk支持会话列表、聊天、好友列表等页面的标题栏风格设置，统一通过UiType枚举值区分。\\ sdk调用流程： {{ :set_title_style.png?nolink&680 }}\\ 代码参考：


/**
 * 给指定页面类型，设置标题栏风格。
 *
 * @param type       需要设置标题栏风格的页面，详情请参考UiType声明。
 * @param config     标题栏风格属性，可以设置标题栏title、颜色、文字颜色、点击事件等，详情请参考ActionBarConfig声明。
 */
UCS_IMUIManager.setActionBarStyle(type,config)

具体示例：


/**
 * 创建ActionBarConfig
 */
ActionBarConfig actionBarConfig = new ActionBarConfig();
/**
 * 设为标题栏颜色为蓝色
 */
actionBarConfig.setActionBarColor("#1100FF");
/**
 * 设置会话列表页面的标题栏风格
 */
UCS_IMUIManager.setActionBarStyle(UCS_IMUIManager.UiType.IMChatList, actionBarConfig);

对比效果： {{ :android_set_titleColor_before_01.png?nolink& }}\\ ==== 2、设置好友列表 ==== 出于隐私方面的考虑，云之讯不维护开发者的好友关系，云之讯sdk提供设置好友列表接口方便开发者灵活的使用。如果用户设置了好友列表，云之讯ui将尽可能的匹配开发者设置的好友列表，如：会话列表页面每条会话的头像和昵称、聊天页面的头像和昵称、讨论组信息页面成员的头像和昵称等，都会匹配开发者设置的好友列表。注意：开发者也可以将当前登录的账号设置到好友列表里面，这样当前登录的账号也有了头像和昵称。\\ sdk调用流程： {{ :android_set_friends.png?nolink&680 }} 代码参考：


/**
 * 设置好友列表。
 *
 * 请开发者保证所有的好友都是注册过的，不然用户在好友列表页面拉取好友进入讨论组会失败。
 * @param contacts       好友(SortModel)集合，其中SortModel的userId属性必须设置，也可以设置头像url(暂时只支持http协议)和昵称name。
 */
UCS_IMUIManager.setFriendListContacts(contacts);

具体示例：


/**
 * 新建好友列表集合
 */
List contacts = new ArrayList();
/**
 * 创建一个好友
 */
SortModel sortModel = new SortModel();
/**
 * 设置好友userId
 */
sortModel.setId("13421340887");
/**
 * 设置好友昵称
 */
sortModel.setName("Marry");
/**
 * 设置好友头像URL
 */
sortModel.setUrl("头像URL");
/**
 * 添加到集合
 */
contacts.add(sortModel);
/**
 * 将好友集合设置给sdk
 */
UCS_IMUIManager.setFriendListContacts(contacts);

界面效果： {{ :android_setFriends_s.png |各界面效果集}} ==== 3、设置群组列表 ==== 云之讯sdk同样既不维护也不保存用户的群组关系，开发者只需在启动会话列表之前设置一次好友列表，后续会话列表里面的群组会话条目将会根据群组id去匹配群组信息。这里需要注意的是：云之讯sdk不会将群组列表保存到数据库中，也不会上传到服务器，用户只需在应用启动之后设置一次即可。\\ sdk调用流程： {{ :android_set_groups.png?nolink&680 }} 代码参考：


/**
 * 设置群组成员列表。
 *
 * @param groups       群组(GroupBean)集合，构造GroupBean时分别传入群组头像url、群组id(不能为null)、群组名称。
 */
UCS_IMUIManager.setGroupBean(groups)

具体示例：


/**
 * 创建群组列表集合
 */
List groups = new ArrayList();
/**
 * 创建名为体验群1的群组
 */
GroupBean groupBean01 = new GroupBean("头像URL","群组id","体验群1");
/**
 * 创建名为体验群2的群组
 */
GroupBean groupBean02 = new GroupBean("头像URL","群组id","体验群2");
/**
 * 将体验群1加入到集合
 */
groups.add(groupBean01);
/**
 * 将体验群2加入到集合
 */
groups.add(groupBean02);
/**
 * 将群组集合设置到sdk
 */
UCS_IMUIManager.setGroupBean(groups);

界面效果： {{ :android_set_groups_s.png |设置群组之后的会话列表页面}} ==== 4、设置消息通知开关 ==== 默认情况下，云之讯sdk在收到新消息时，如果当前应用出于后台，将会在通知栏弹出消息通知，并且添加震动。开发者可以关闭消息通知和震动开关，开发者需要注意的是：消息通知和震动开关只支持一起关闭或者打开。\\ 通知栏效果： {{ :android_setNotification_p.png?nolink }} 代码参考：


/**
 * 设置消息通知开关。
 *
 * @param context       应用的上下文。
 * @param loalUser      当前登录用户id。
 * @param on            是否开启消息通知开关，false表示关闭，true表示开启，默认是true。
 */
UCS_IMUIManager.setMsgNotification(context,loalUser,on);