Android

本文介绍如何创建一个 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 工程，可以开始编码了。

你可以使用远程依赖的方式使用 Graldlew 依赖 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 版本号，最新版本号参看资源获取。

dependencies {
    api 'com.bytedance.im:imsdk-tob:1.x.x'
}

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

   

   注意

   如出现 65535 问题报错，可通过配置 multiDexEnabled true 解决。
   报错信息：

   Cannot fit requested classes in a single dex file (# methods: 67777 > 65536)
   

   解决方案：

   defaultConfig {
       multiDexEnabled true
   }
   

本地依赖方式

1. 下载 SDK 的 AAR 文件到本地，解压出 imsdk.jar 并拷贝文件到 lib。

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.im.*{ *; }

初始化

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

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

    }
});

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

//方式 2: 使用默认方式，日志打印到 logcat
BIMClient.getInstance().initSDK(this, appId, null);

BIMLogLevel 日志级别含义如下

设置监听

设置 Imsdk 生命周期内重要事件的监听可以了解 IMSDK 的运行状态，数据同步状态等信息，便于开发者业务逻辑判断。

• 长链接状态监听 onConnectStatusChanged 方法回调当前长链接状态，如果长链接不可用时收发消息将会受到影响。onTokenInvalid 方法在 token 过期时会回调。

  BIMClient.getInstance().addConnectListener(new BIMConnectListener() {
      @Override
      public void onConnectStatusChanged(BIMConnectStatus bimConnectStatus) {
  
      }
  
      @Override
      public void onTokenInvalid(BIMErrorCode bimErrorCode) {
  
      }
  });
  

登录登出

完成初始化并设置监听后，即可进入到登录流程。

• 客户端登录

客户端登录示例代码如下。登录会根据当前传入的 uid，token 鉴权，并拉取历史会话、消息等数据，同时建立长链接。

BIMClient.getInstance().login(uid, token, new BIMSimpleCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(BIMErrorCode bimErrorCode) {

    }
});

• 获取当前登录用户

• 客户端登出

  BIMClient.getInstance().logout();
  

• 账号切换

开发者可以通过 logout 当前账号，再 login 新账号实现此功能。

实现单聊

通过以下简单步骤可实现单聊功能，单聊是 IM 的基础功能，能够实现一对一的即时通信能力。

1. 创建单聊会话

BIMClient.getInstance().createSingleConversation(toUid, new BIMResultCallback<BIMConversation>() {
    @Override
    public void onSuccess(BIMConversation bimConversation) {

    }

    @Override
    public void onFailed(BIMErrorCode bimErrorCode) {

    }
});

2. 发送单聊消息

//创建消息
BIMMessage bimMessage = BIMClient.getInstance().createTextMessage("消息内容");
//发送消息
BIMClient.getInstance().sendMessage(bimMessage, conversationId, new BIMSendCallback() {
    @Override
    public void onProgress(BIMMessage bimMessage, int i) {
        //发送进度（0～100），仅多媒体消息
    }

    @Override
    public void onSaved(BIMMessage bimMessage) {
        //消息保存到本地
    }

    @Override
    public void onSuccess(BIMMessage bimMessage) {
        //消息发送成功
    }

    @Override
    public void onError(BIMMessage bimMessage, BIMErrorCode bimErrorCode) {
        //发送错误
    }
});

3. 设置消息监听

BIMClient.getInstance().addMessageListener(new BIMMessageListener() {
    @Override
    public void onReceiveMessage(BIMMessage bimMessage) {
        //收到消息
    }

    @Override
    public void onSendMessage(BIMMessage bimMessage) {
        //发送消息
    }

    @Override
    public void onDeleteMessage(BIMMessage bimMessage) {
        //删除消息
    }

    @Override
    public void onRecallMessage(BIMMessage bimMessage) {
        //撤回消息
    }

    @Override
    public void onUpdateMessage(BIMMessage bimMessage) {
        //更新消息
    }
});

海外服务

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

//BIMEnv.I18N.getEnv() 代表海外环境
//BIMEnv.DEFAULT_ZH.getEnv() 代表国内环境
BIMClient.getInstance().initSDK(application, appId, config, BIMEnv.I18N.getEnv());

配置日志

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

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

相关文档

• IM Cloud API

• IM Cloud 回调

• IM Cloud 错误码

• IM Cloud 类型详情