====== IM Android UI组件开发指南 ======

说明：本指南是Android平台的接入说明，方便有Android研发基础的开发者快速了解整合云之讯即时通讯界面组件。本指南只包含paas服务器连接和IM界面组件的使用操作。如需开发出针对企业和开发者所需的个性化应用，仍然需要具备一定的Android开发经验。

===== 一、UIKit界面组件介绍 =====
云之讯IM UIKit是在原子SDK的基础上封装了IM相关的上层业务和UI，开发者无须处理复杂IM业务及UI，只需启动已封装好的界面就能拥有IM功能。包括：IM会话列表界面、好友列表界面、聊天界面等。 \\ 

如果你还没有下载UIKit开发包，请前往云之讯官网下载IMKit（[[http://www.ucpaas.com/product_service/im#item4|下载地址]]），IMKit界面组件开发包含以下部分：\\
  *1、UCS_Android_UIKIT_IM.zip，包含了库文件和资源文件。\\

===== 二、IMKit接入工程的准备 =====
==== 1、开发准备 ====
这里以Eclipse为例，首先搭建好Android开发环境，满足以下要求：

  *Android SDK Build-tools 请升级到 21 及以上版本。
  *JAVA 编译版本 JDK 1.7 及以上版本。
  *使用 IMKit 需要 Android Support V4 21 及以上版本。
  *Android SDK 最低支持 Android API 9: Android 2.3(Gingerbread)。 

用户创建好自己的Android Application Project，接下来就可以开始导入我们的IMKit界面组件了。
==== 2、导入工程的操作 ====
将IMUISDK.rar解压，得到libs和res两个文件夹，将这两个文件夹复制到工程根目录下，与工程原有的两个同名文件夹合并，从而将SDK中的库文件及资源文件添加到工程中，合并后工程效果如下：

{{ :im_sdk_1.jpg?200 |}}

==== 3、继承IMKit中的Application ====
用户在工程中新建继承自YZXMainApplication的类，并在其onCreate()方法中调用父类的onCreate()方法，类代码如下： 
  
  public class MainApplication extends YZXMainApplication { 
    @Override
    public void onCreate() {
        super.onCreate();
    }
  }
 
另外还需在AndroidManifest.xml文件添加MainApplication声明，如下： 
  <application 
      android:name=".MainApplication"
  </application> 
==== 4、添加权限和组件声明 ====
在工程的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="com.android.launcher.permission.READ_SETTINGS" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.GET_TASKS" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <!--百度地图需要的权限-->
    <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" />
    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <!--这里输入百度密钥-->
        <meta-data
            android:name="com.baidu.lbsapi.API_KEY"
            android:value="5ZVIGi4nwol98XwTnY26DFnF" />
        <!--百度的远程服务-->
        <service
            android:name="com.baidu.location.f"
            android:enabled="true"
            android:process=":remote" />
        <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.IMDiscussListActivity" />
        <activity android:name="com.yzx.im_UIdemo.IMDiscussInfoActivity" />
        <activity android:name="com.yzx.im_UIdemo.IMGroupListActivity" />
        <activity android:name="com.yzx.im_UIdemo.IMImageActivity" />
        <service android:name="com.yzxtcp.service.YzxIMCoreService" />
        <receiver android:name="com.yzxtcp.tools.tcp.receiver.AlarmReceiver" />
        <receiver android:name="com.yzxIM.tools.tcp.receiver.MsgBackReceiver" />
    </application>
===== 三、IMKit快速集成 =====
IMKit提供的接口都在UCS_IMUIManager类中以静态函数的形式提供的，使用前需在相应文件中导入com.yzx.im_UIdemo.UCS_IMUIManager，代码为： 
  import com.yzx.im_UIdemo.UCS_IMUIManager; 
==== 1、登录云平台 ====
IMKit为登录云平台提供了两个接口，一个使用token登录，一个使用账号密码登录 

通过token登录云平台:
<code java>
/**
 *
 * @param token 客户端向接入服务器请求得到的一串字符，新注册的账号只能使用token的方式登录云平台。
 * @param listener 登陆回调监听
*/
static void connect(java.lang.String token,ILoginListener listener)
</code>
通过账号密码登录云平台: 
<code java>
/**
 *
 * @param sid 开发者账号
 * @param sidPwd 开发者账号密码
 * @param clientId 子账号
 * @param clientPwd 子账户密码
 * @param loginCallBack 登陆回调
*/
static void connect(String sid,String sidPwd,String clientId,String clientPwd,ILoginListener listener)
</code>

下面以token登录为例说明其用法，在参数中传入token字符串及回调，示例代码如下： 
<code java>
ILoginListener listener = new ILoginListener() {
    @Override
    public void onLogin(UcsReason reason) {
        if (reason.getReason() == UcsErrorCode.NET_ERROR_CONNECTOK) {
            //登陆成功
        } else {
            //登陆失败
        }
    }
};
UCS_IMUIManager.connect("xxx_token", listener);
</code>
==== 2、退出云平台 ====
退出接口为：
<code java>
static void disconnect()
</code>
调用UCS_IMUIManager.disconnect()即可断开与云平台的连接，断开后客户端将不再与云平台进行包括心跳包在内的数据交互，该客户端将被服务器视为离线状态。

==== 3、启动会话列表界面 ====

跳转到会话列表界面：
<code java> 
/**
 *
 * @param context 上下文
 * @param localUser 当前登录账号
 * @param nickName 当前登录账号昵称
*/
static void startIMChatActivity(Context context, java.lang.String localUser, java.lang.String nickName)
</code>

 
==== 4、启动好友列表界面 ====
跳转到好友列表界面：
<code java>
/**
 *
 * @param context 上下文
 * @param localUser 当前登录账号
 * @param nickName 当前登录账号昵称
*/
static void startIMFriendListActivity(Context context,String localUser,String nickName) 
</code>
 
==== 5、启动聊天界面 ====
跳转到聊天界面
<code java>
/**
 *
 * @param context 上下文
 * @param localUser 用户账号
 * @param nickName 用户昵称
 * @param targetID 对方账号
 * @param targetNickName 对方昵称
 * @param categoryId 聊天种类
 * @return 跳转参数是否正确
*/
  static boolean startIMMsgActivity(Context context,String localUser,String nickName,String targetID, String targetNickName, CategoryId categoryId)
</code>
            
===== 四、自定义 =====
==== 1、设置标题栏风格 ====
IMKit中的界面标题栏有默认风格，用户也可调用下面接口更改界面风格：
<code java>
/**
 *
 * @param type 需要设置风格的界面，详情请参考UCS_IMUIManager.UiType说明
 * @param config 标题栏配置参数，详情请参考ActionBarConfig类说明
*/
static void setActionBarStyle(UCS_IMUIManager.UiType type, ActionBarConfig config)
</code>
下面以更改会话列表界面的标题栏的背景色为例来说明该接口的使用：
<code java> 
//设置标题栏风格
ActionBarConfig actionBarConfig = new ActionBarConfig();
actionBarConfig.setActionBarColor("#3299CC");//设为天蓝色
UCS_IMUIManager.setActionBarStyle(UCS_IMUIManager.UiType.IMChatList, actionBarConfig);
</code> 
设置前后效果图如下:
{{ :im_sdk_3.png?nolink&300 |}}
{{ :im_sdk_4.png?nolink&300 |}}
==== 2、设置好友列表成员 ====
设置好友列表成员: 
<code java>
/**
 *
 * @param contacts 好友列表
*/
static void setFriendListContacts(List<SortModel> contacts);
</code>
调用该接口后指定的联系人将被添加到好友列表中，并且会话列表中的单聊会话会根据id来匹配头像、title信息。
<code java>
//设置好友列表成员
List<SortModel> contacts = new ArrayList<SortModel>();
SortModel sortModel = new SortModel();
sortModel.setName("Marry");//好友昵称
sortModel.setId("13421340887");//好友ID
sortModel.setUrl("头像URL");//好友头像URL
contacts.add(sortModel);
UCS_IMUIManager.setFriendListContacts(contacts);
</code>
好友列表页面效果如下：
 {{ :im_sdk_friends03.png?nolink&300 |}}
会话列表页面效果如下：
 {{ :im_sdk_conversitionList02.png?nolink&300 |}}
  
==== 3、设置群组列表成员 ====
设置群组列表成员:
<code java>
/**
 *
 * @param groupBeans 群组列表
*/
static void setGroupBean(List<GroupBean> groups);
</code> 
调用该接口后，会话列表中的群组会话将会按照设置的群组id来匹配头像、title信息。 

<code java>
//设置群组列表成员
List<GroupBean> groups = new ArrayList<GroupBean>();
GroupBean groupBean01 = new GroupBean("头像URL","群组id","体验群1");
GroupBean groupBean02 = new GroupBean("头像URL","群组id","体验群2");
groups.add(groupBean01);
groups.add(groupBean02);
UCS_IMUIManager.setGroupBean(groups);
</code>
会话列表效果如下:
 {{ :im_sdk_group_01.png?nolink&300 |}}

==== 4、设置消息通知是否开启 ====
设置通知栏消息(包括震动与声音)是否开启：
<code java>
/**
 * 
 * @param context 上下文
 * @param localUser 当前登录用户
 * @param on true为开启，false为关闭
 */
static void setMsgNotification(Context context, String loalUser,boolean on);
</code>


===== 五、属性说明 =====
==== 1、UiType ====
UiType定义了可设置风格的界面 可以使用该枚举指定需要设置的界面，具体定义如下:
<code java>
public static enum UiType {
IMChatList,//会话列表界面
IMMessage,//聊天界面
IMFriendList,//好友列表界面
IMPersonInfo,//单聊设置界面
IMDiscussionInfo,//讨论组设置界面
IMMSGBackGroud,//聊天背景
IMSelBackGroud;//选择背景
}
</code>
==== 2、ActionBarConfig ====
配置ActionBar风格类,支持ActionBar左右两侧图片及点击响应自定义,支持ActionBar背景颜色及文字颜色自定义。
用户可以通过set方法进行参数的配置如：
<code java>
ActionBarConfig config = new ActionBarConfig();
config.setActionBarColor(0xff000000);//设置actionBar背景色
config.setTitle("消息");//设置actionBar的title文字
</code>
ActionBarConfig具体属性如下：
<code java>
public class ActionBarConfig{
public int mLeftImageID,mRightImageID;//actionBar左右两边的图标资源id
	
public OnClickListener mLeftImageClick, mRightImageClick;//actionBar左右两边的图标点击事件
	
public String mActionBarColor,mTitleColor;//actionBar背景色和title文字颜色，如："blue","green","red","yellow"等
	
public String mTitle;//actionBar的title文字
	
public int mLeftImageVisi,mRightImageVisib;//actionBar左右两边的图标可见性,与View.VISIBLE、View.INVISIBLE、View.GONE一样用法
	
public int mActionBarColorInt,mTitleColorInt;//actionBar背景色和title文字颜色值，如0xff000000
}
</code>

===== 六、注意事项 =====
==== 1、百度key认证错误 ====
如果在使用地图功能时报  **"请检查key,baiduSDK认证错误!"**
  需要用户在AndroidManifest.xml文件中修改
  <meta-data
            android:name="com.baidu.lbsapi.API_KEY"
            android:value="用户在百度申请的KEY" />