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

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

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

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

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

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

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

步骤 2:集成 SDK

你可以使用远程依赖的方式使用 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'
    // 1.17.0 及以上版本需要依赖上报组件, 上报组件版本与imsdk-tob组件版本一致
    // 国内上报组件
    // api 'com.bytedance.im:imsdk-tob-log:1.x.x'
    // 海外上报组件
    // api '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 的 AAR 文件到本地,解压出 imsdk.jar 并拷贝文件到 lib。

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

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

步骤 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: 开发者实现日志打印逻辑,如写入文件上报服务等。
BIMClient.getInstance().initSDK(this, appId, config);

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

BIMLogLevel 日志级别含义如下

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

设置监听

设置 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) {

    }
});
  1. 发送单聊消息
//创建消息
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) {
        //发送错误
    }
});
  1. 设置消息监听
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);

相关文档