You need to enable JavaScript to run this app.
导航
Android
最近更新时间:2024.09.25 17:59:09首次发布时间:2023.05.29 20:17:24

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

前提条件
步骤 1:创建项目(可选)

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

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

  1. 在 New Project 窗口中,选择 Empty Activity,然后单击 Next

  1. 在 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 复选框。

  1. 单击 Finish,经过一段时间的处理后,Android Studio 主窗口会出现,同时你已经构建好了 Android 工程,可以开始编码了。
步骤 2:集成 SDK

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

远程依赖方式

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

  1. 项目切换为 project 视图,修改项目中仓库配置添加 maven 仓库,示例代码如下。
repositories {
    maven {
        url "https://artifact.bytedance.com/repository/Volcengine/"
    }
}
  1. 修改 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'
}
  1. 使用 Gradle 的 Sync 功能,同步 SDK 到本地集成到工程中。

注意

如出现 65535 问题报错,可通过配置 multiDexEnabled true 解决。
报错信息:Cannot fit requested classes in a single dex file (# methods: 67777 > 65536)
解决方案:defaultConfig { multiDexEnabled true }

本地依赖方式

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

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

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}
  1. 其他步骤同远程依赖方式集成。
步骤 3:配置 App 权限

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" />
步骤 4:配置混淆

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

-keep class com.bytedance.**{*;}
步骤 5:初始化

在使用 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 日志级别含义如下

日志级别含义
BIM_LOG_DEBUGdebug 日志, 调试信息。
BIM_LOG_INFOInfo 日志,上下文环境等信息。
BIM_LOG_WARNwarn 日志,警告信息。
BIM_LOG_ERRORerror 日志,错误信息。

海外服务

在 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);
步骤 6:登录登出

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

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

    @Override
    public void onFailed(BIMErrorCode code) {
        //登录失败
    }
});
步骤 7:集成会话列表页面

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)

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

步骤 8:集成消息列表页面

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);
    }
});

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