本篇文档旨在帮助开发者快速集成云之讯android UI组件，云之讯IM UIKit是在原子sdk的基础上封装了IM相关的上层业务和UI，开发者无须处理复杂IM业务及UI，只需启动已封装好的界面就能拥有IM功能。包括：IM会话列表界面、好友列表界面、聊天界面等。
云之讯提供UCS_IMUIManager控制类方便开发者调用，所有的对外接口都以静态函数的形式供开发者使用。

开发者账号是使用云之讯通讯能力的通行证，如果您还未注册开发者账号，或者希望创建一个新的开发者账号，请前往:云之讯账户系统注册开发者账号。

注册时,请您使用真实的手机号码和邮箱，以方便我们向您发送重要通知并在紧急时刻能够联系到您。

如果您想了解更多,请前往云之讯开发者账户指南。

完成开发者账号注册后，在为您的APP集成云之讯能力之前，您需要前往云之讯开发者控制台创建应用，这个应用和您需要集成云之讯能力的APP是一对一的对应关系。

您可以点击页面左上方创建应用按钮开始创建一个应用。在创建应用界面，您需要填写应用名称、应用类型、所属行业三个必选项。云之讯强烈建议您设置服务器白名单，设定白名单地址后，云之讯服务器在识别该应用请求时将只接收白名单内服务器发送的请求，能有效提升帐号安全性。 如未设置默认不生效。如果您的应用需要使用到高级配置中的能力，您需要勾选对应的能力项。

如果您想了解更多,请前往云之讯管理平台使用指南。

如果您还未下载uiKitSDK，您可以通过云之讯官网下载uiKit SDK，压缩包中分为两部分：

• 1) libs目录：uiKit sdk依赖的jar包和动态库(.so文件)
• 2) res文件夹目录：uiKit sdk依赖的资源文件，为了避免和开发者的资源冲突，uiKit sdk的资源文件都以yzx开头。

如果您还未创建应用，那么请您先创建一个空项目来导入云之讯IM SDK。这里我们以Eclipse为例，后面的操作也是如此。
如图我们创建了一个名为MyApp的空项目：

将压缩包里面的libs和res文件夹拷贝到自己工程与之对应的目录，放置好的效果如下图所示：

将下列权限添加到AndroidManifest.xml文件中

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<uses-permission android:name="android.permission.VIBRATE" />
<!--地图功能需要百度地图的权限-->
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />
<uses-permission android:name="android.permission.MANAGE_ACCOUNTS" />
<uses-permission android:name="android.permission.AUTHENTICATE_ACCOUNTS" />
<uses-permission android:name="android.permission.BROADCAST_STICKY" />

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

<!--这里输入百度密钥-->
<meta-data
    android:name="com.baidu.lbsapi.API_KEY"
    android:value="开发者申请的密钥" />

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

<!-- YzxIMCoreService是云之讯IM的核心服务 -->
<service android:name="com.yzxtcp.service.YzxIMCoreService" />
<!--百度的远程服务-->
<service android:name="com.baidu.location.f" android:enabled="true" android:process=":remote" />
<!-- AlarmReceiver和MsgBackReceiver是维持TCP长连接心跳的广播 -->
<receiver android:name="com.yzxtcp.tools.tcp.receiver.AlarmReceiver" />
<receiver android:name="com.yzxtcp.tools.tcp.receiver.MsgBackReceiver" />

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

<!--会话列表页面-->
<activity
          android:name="com.yzx.im_UIdemo.IMChatActivity"
          android:screenOrientation="portrait" />
<!--聊天页面-->
<activity 
          android:name="com.yzx.im_UIdemo.IMMessageActivity" 
          android:windowSoftInputMode="stateHidden|adjustResize"/>
<!--自定义消息页面-->
<activity
          android:name="com.yzx.im_UIdemo.IMCustomMsgActivity"
          android:configChanges="keyboardHidden|orientation|screenSize"
          android:screenOrientation="portrait"
          android:windowSoftInputMode="stateHidden|adjustResize" />
<!--地图查看页面-->
<activity
          android:name="com.yzx.im_UIdemo.IMBaiduMapActivity"
          android:screenOrientation="portrait"
          android:theme="@android:style/Theme.Light.NoTitleBar" />
<!--广播页面-->
<activity
          android:name="com.yzx.im_UIdemo.IMBroadcastActivity"
          android:screenOrientation="portrait" />
<!--踢线页面-->
<activity
          android:name="com.yzx.im_UIdemo.IMLoginOutActivity"
          android:screenOrientation="portrait"
          android:windowSoftInputMode="stateHidden|adjustPan" >
          <intent-filter>
              <action android:name="android.intent.action.VIEW" />
              <category android:name="android.intent.category.DEFAULT" />
              <data
                  android:host="com.yzx.im_ui"
                  android:pathPrefix="/login_out"
                  android:scheme="yzx" />
          </intent-filter>
</activity>
<!--消息信息页面-->
<activity android:name="com.yzx.im_UIdemo.IMMessageInfoActivity" />
<!--背景页面-->
<activity android:name="com.yzx.im_UIdemo.IMMessageBgActivity" />
<!--选择背景页面-->
<activity android:name="com.yzx.im_UIdemo.IMSelectBgActivity" />
<!--好友列表页面-->
<activity android:name="com.yzx.im_UIdemo.IMFriendListActivity" />
<!--讨论组信息页面-->
<activity android:name="com.yzx.im_UIdemo.IMDiscussInfoActivity" />
<!--查看图片页面-->
<activity android:name="com.yzx.im_UIdemo.IMImageActivity" />

初始化操作旨在启动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);
    }
}

云之讯认为，每位开发者在调用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方法连接云平台。

用户未注册流程：
用户已注册流程：
这里有两点需要注意的地方：

• 1) app Server：指的是开发者后台服务器
• 2) app用户：指的是使用开发者应用的用户

登录流程里面已经进行过说明，云之讯后台服务器是通过Token唯一标识一个app用户。开发者在连接服务器之前，需要将app用户输入的userId提交到App Server，获取到与userId对应的Token。App Server获取Token的方法请参考IM服务端开发文档。

在链接服务器之前，请您确认已经通过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());
    }
  }
});

云之讯对外只提供会话列表、聊天、好友列表三个页面。再启动页面之前，请确保已经连接上服务器，并且页面已经配置完毕。

会话列表页面是所有会话的集中地，云之讯会自动更新页面上的内容包括：未读消息数、会话最后消息时间、会话排序等。

/**
 * 启动会话列表界面
 *
 * 开发者应该将当前登录的账号和昵称传递给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;
  }
});

效果图如下：

聊天页面是用户之间交互的页面，聊天页面可以实现发送文字、语音、图片、位置信息等内容。

/**
 * 启动聊天页面
 *
 * @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;
  }
})

效果图如下：

云之讯的好友列表页面每个好友条目前面都会有一个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;
  }
});

效果图如下：

云之讯sdk为开发者提供丰富的自定义功能，开发者可以调用相应的接口轻松完成自定义的效果。云之讯sdk提供的自定义包括：标题栏自定义、好友列表自定义、群组列表自定义、消息通知自定义。

云之讯sdk默认的标题栏风格为绿色，开发者需要在页面启动前设置标题栏风格才有效果。云之讯sdk支持会话列表、聊天、好友列表等页面的标题栏风格设置，统一通过UiType枚举值区分。
sdk调用流程：
代码参考：

/**
 * 给指定页面类型，设置标题栏风格。
 *
 * @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);

对比效果：

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

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

具体示例：

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

界面效果：

云之讯sdk同样既不维护也不保存用户的群组关系，开发者只需在启动会话列表之前设置一次好友列表，后续会话列表里面的群组会话条目将会根据群组id去匹配群组信息。这里需要注意的是：云之讯sdk不会将群组列表保存到数据库中，也不会上传到服务器，用户只需在应用启动之后设置一次即可。
sdk调用流程： 代码参考：

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

具体示例：

/**
 * 创建群组列表集合
 */
List<GroupBean> groups = new ArrayList<GroupBean>();
/**
 * 创建名为体验群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);

界面效果：

默认情况下，云之讯sdk在收到新消息时，如果当前应用出于后台，将会在通知栏弹出消息通知，并且添加震动。开发者可以关闭消息通知和震动开关，开发者需要注意的是：消息通知和震动开关只支持一起关闭或者打开。
通知栏效果： 代码参考：

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

UiType是对云之讯UI组件类型的抽象，代表了云之讯UI组件所支持的页面类型，UiType是个枚举类型。
下面就是UiType各枚举值的意义：

云之讯sdk将actionBar的设置抽象成ActionBarConfig 这个类，类属性代表可以自定义的功能，开发者可以通过set方法设置属性，如：setTitle表示设置title文字、setActionBarColor表示设置title背景色。