本文介绍如何创建一个 IMCloud Android 项目，实现即时通讯功能。你也可以通过阅读代码，了解即时通讯的最佳实践。

• 获取 AppID 和 Token，你可以通过阅读密钥说明了解更多 Token 相关信息

• JDK 1.8+

• Android 4.4+

• Android API Level 19+

本步骤为如何创建一个新项目，如集成到已有项目，请直接查看集成 SDK。

1. 打开 Android Studio。在 Welcome to Android Studio 窗口中，单击 New Project。

2. 在 New Project 窗口中，选择 Empty Activity，然后单击 Next。

3. 在 Empty Activity 窗口中，完成以下操作：

   1. 在 Name 字段中输入Hello IMCloud。

   2. 在 Package name 字段中输入com.example.imclouddemo。

   3. 在 Save location 中输入项目的存储路径。

   4. 从 Language 下拉菜单中选择 Java 或者 kotlin。

   5. 在 Minimum SDK 字段中选择 API 19 作为应用支持的最低 Android 版本。

   6. 如果应用需要旧版库支持，选中 Use legacy android.support libraries 复选框。

4. 单击 Finish，经过一段时间的处理后，Android Studio 主窗口会出现，同时你已经构建好了 Android 工程，可以开始编码了。

你可以使用远程依赖的方式使用 gradlew 依赖 IMSDK，或者本地依赖手动下载 IMSDK AAR 导入到项目中。

远程依赖方式

开发者可以修改 gradle 依赖配置，依赖已经发布到 maven 仓库的 IMSDK。

1. 项目切换为 project 视图，修改项目中仓库配置添加 maven 仓库，示例代码如下。

repositories {
    maven {
        url "https://artifact.bytedance.com/repository/Volcengine/"
    }
}

2. 修改 app module 中的 build.gradle 添加 imsdk 依赖，如下图。

添加依赖示例代码如下，你需要填写所需要的 SDK 版本号，IM SDK v1.1.1+ 支持含 UI 集成方案，最新版本号参看资源获取。

dependencies {
    implementation 'com.bytedance.im:im-uikit-tob:1.x.x'
    implementation 'com.bytedance.im:imsdk-tob:1.x.x'
    // 1.17.0 及以上版本需要依赖上报组件, 上报组件版本与imsdk-tob组件版本一致
    // 国内上报组件
    // implementation 'com.bytedance.im:imsdk-tob-log:1.x.x'
    // 海外上报组件
    // implementation 'com.bytedance.im:imsdk-tob-log-global:1.x.x'
}

3. 使用 Gradle 的 Sync 功能，同步 SDK 到本地集成到工程中。

本地依赖方式

1. 下载 SDK 和 UIKit 到本地，解压并拷贝文件到 lib。其中 UIKit 已经开源，你也可以通过 GitHub 仓库获取 UIKit 源码。

2. 检查 app 模块下 build.gralde 是否存在如下代码，如不存在需要手动添加。

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

3. 其他步骤同远程依赖方式集成。

在 AndroidManifest.xml 中配置 App 相关权限，其中 IM 收发消息及数据同步需要网络相关权限，发送图片、视频等媒体信息需要使用磁盘读写权限。

<!--  网络相关  -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<!--  读写磁盘  -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

在 proguar-rulers.pro 中配置混淆,如下

-keep class com.bytedance.**{*;}

在使用 IMSDK 接口功能前需要先进行初始化操作，在 application 的 onCreate() 回调函数中添加如下代码。其中 BIMSDKConfig 可配置 IMSDK 的日志监听。

BIMSDKConfig config = new BIMSDKConfig();
config.setLogListener(new BIMLogListener() {
    @Override
    public void onLog(BIMLogLevel bimLogLevel, String tag, String content) {

    }
});

//方式 1：开发者实现日志打印逻辑，如写入文件上报服务等。
BIMUIClient.getInstance().init(this,APP_ID,config);

//方式 2：使用默认方式，日志打印到 logcat
BIMUIClient.getInstance().init(this,APP_ID,null);

BIMLogLevel 日志级别含义如下

海外服务

在 v1.9.0 及之后版本，IM SDK 同时支持海外服务，你可以在初始化时配置海外环境，示例代码如下。

//BIMEnv.I18N.getEnv() 代表海外环境
//BIMEnv.DEFAULT_ZH.getEnv() 代表国内环境
BIMUIClient.getInstance().init(application,curAppId, BIMEnv.I18N.getEnv(), config);

配置日志

IM SDK 提供了日志记录和性能分析功能，以帮助用户分析线上问题，默认开启。为了更好地排查问题，SDK 会上报部分客户端数据到火山国内的监控服务，如评估后有风险，可以在 initSDK 时配置 BIMSDKConfig 关闭日志功能，示例代码如下。

//配置开关
BIMSDKConfig config = new BIMSDKConfig();
config.setEnableAPM(false);         //日志记录功能
config.setEnableAppLog(false);      //性能监控功能
//初始化
BIMUIClient.getInstance().initSDK(application,appId, config);

完成初始化并设置监听后，即可进入到登录流程，登录后才能正常使用组件功能，客户端登录示例代码如下。登录会根据当前传入的 uid，token 鉴权，并拉取历史会话、消息等数据，同时建立长链接。

BIMUIClient.getInstance().login(uid, token, new BIMSimpleCallback() {
    @Override
    public void onSuccess() {
        //登录成功
    }

    @Override
    public void onFailed(BIMErrorCode code) {
        //登录失败
    }
});

BIMConversationListFragment 提供了会话列表页面的实现，你可以像普通的 Fragment 一样嵌入你的 UI 布局 XML，或者将代码动态加载到你的 UI 代码上，以下代码是 XML 示例。

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:orientation="vertical">

   //...

    <fragment
        android:name="com.bytedance.im.ui.conversation.BIMConversationListFragment"
        android:id="@+id/conversation_list"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>
</LinearLayout>

BIMConversationListFragment 提供了点击监听，便于业务自定义会话点击事件。

/**
 * 设置会话列表 item 监听
 * @param onItemClickListener item 点击监听
 */
public void setOnItemClickListener(OnConversationClickListener onItemClickListener)

集成后会话列表页面实现样式参考下图：

BIMConversationListFragment 提供了消息列表页面的实现，你可以像普通的 Fragment 一样嵌入你的 UI 布局 XML，或者将代码动态加载到你的 UI 代码上，以下代码是 XML 示例。

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">
    <fragment
        android:id="@+id/message_fragment"
        android:name="com.bytedance.im.ui.message.BIMMessageListFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</LinearLayout>

隐式启动

在内嵌 BIMMessageListFragment 的 Activity 配置启动 action 为 "com.bytedance.im.page.message_list"，示例代码如下。

<activity
    android:name=".message.VEMessageListActivity"
    android:screenOrientation="portrait">
    <intent-filter>
        <category android:name="android.intent.category.DEFAULT" />
        <action android:name="com.bytedance.im.page.message_list" />
    </intent-filter>
</activity>

显式启动

使用 Intent 显示指定 Activity，启动时需携带当前会话的会话 id。以会话列表设置监听并启动为例，示例代码如下。

bimConversationListFragment.setOnItemClickListener(new BIMConversationListFragment.OnConversationClickListener() {
    @Override
    public void onConversationClick(BIMConversation conversation) {
    //启动消息列表 Activity
        Intent intent = new Intent();
        intent.setAction(BIMMessageListFragment.ACTION);
        //携带会话 ID
        intent.putExtra(BIMMessageListFragment.TARGET_CID, conversation.getConversationID());
        startActivity(intent);
    }
});

集成后消息列表页面实现样式参考下图：