集成 SDK

本文介绍如何将即时通讯 IM SDK 集成到你的 Android 项目。

开发环境要求

• Android Studio 3.6 或以上版本；
• Android SDK API 等级 21 或以上；
• Android 5.0 或以上版本的设备。

集成 SDK

选择如下任意一种方式将即时通讯 IM SDK 集成到你的项目中。

提示

以下集成方式只需选择一种，同时使用多种集成方式可能会报错。

方法一：使用 mavenCentral 自动集成

1. 在项目的 settings.gradle 中添加 mavenCentral() 仓库。

pluginManagement {
    repositories {
        ……
        mavenCentral()
        ……
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ……
        mavenCentral()
    }
}

2. 在 module 的 build.gradle 中添加如下依赖：

...
dependencies {
    ...
    // x.y.z 请填写具体版本号，如：1.3.2。
    implementation 'cn.shengwang:chat-sdk:1.3.2'
}

若要查看最新版本号，请点击这里。

方法二：本地集成（将jar包和so文件拷贝到项目中）

打开 SDK 下载页面，获取最新版的即时通讯 IM Android SDK，然后解压。

将 SDK 包内 libs 路径下的如下文件，拷贝到你的项目路径下：

文件或文件夹	项目路径
agorachat_xxx.jar 文件	/app/libs/
arm64-v8a 文件夹	/app/src/main/jniLibs/
armeabi-v7a 文件夹	/app/src/main/jniLibs/
x86 文件夹	/app/src/main/jniLibs/
x86_64 文件夹	/app/src/main/jniLibs/

如果对生成的 apk 大小比较敏感，我们建议使用 jar 方式，并且手工拷贝 so，而不是使用 aar，因为 aar 方式会把各个平台的 so 文件都包含在其中。采用 jar 方式，可以仅保留一个 ARCH 目录，建议仅保留 armeabi-v7a，这样虽然在对应平台执行的速度会降低，但是能有效减小 apk 的大小。

方法三：本地集成(动态加载 .so 库文件)

为了减少应用安装包的大小，SDK 提供了 ChatOptions#setNativeLibBasePath 方法支持动态加载 SDK 所需的 .so 文件。以 SDK 1.3.2 为例，.so 文件包括 libcipherdb.so 和 libagora-chat-sdk.so 、 libaosl.so 三个文件**。

该功能的实现步骤如下：

1. 下载最新版本的 SDK 并解压缩。
2. 集成 agorachat_1.3.2.jar 到你的项目中。
3. 将所有架构的 .so 文件上传到你的服务器，并确保应用程序可以通过网络下载目标架构的 .so 文件。
4. 应用运行时，会检查 .so 文件是否存在。如果未找到，应用会下载该 .so 文件并将其保存到你自定义的应用程序的私有目录中。
5. 调用 ChatClient#init 初始化前，将 .so 文件所在的 app 私有目录作为参数设置进 ChatOptions#setNativeLibBasePath 方法中。
6. 调用 ChatClient#init 初始化后，SDK 会自动从指定路径加载 .so 文件。

提示

1. 该方法仅适合手动集成 Android SDK，不适用于通过 Maven Central 集成。
2. so 库的路径取决于 ChatOptions#setNativeLibBasePath 方法的 path 参数：

• 若设置了 path 参数，SDK 内部会使用 System.load 从设置的路径下搜索和加载 so 库。该路径必须为有效的 app 的私有目录路径。
• path 参数为空或者不调用该方法时，SDK 内部会使用 system.loadLibrary 从系统默认路径中搜索并加载 so 库。

//假设用户已经通过动态下发的方式，将即时通讯 IM SDK 中的 libcipherdb.so 和 libagora-chat-sdk.so、libaosl.so 三个 so 库，放到 app 的 /data/data/packagename/files 目录下。
String filesPath = mContext.getFilesDir().getAbsolutePath();

ChatOptions options = new ChatOptions();
options.setNativeLibBasePath(filesPath);

ChatClient.getInstance().init(mContext, options);

添加项目权限

根据场景需要，在 /app/src/main/AndroidManifest.xml 文件中添加如下行，获取相应的设备权限：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="https://schemas.android.com/apk/res/android"
    package="Your Package"
    android:versionCode="100"
    android:versionName="1.0.0">

    <!-- IM SDK required start -->
    <!-- 允许程序振动，用于本地通知设置振动 -->
    <uses-permission android:name="android.permission.VIBRATE" />
    <!-- 访问网络权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- 麦克风权限，用于语音消息时录制语音，不使用录制语音可以移除 -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <!-- 相机权限，用于图片消息时拍摄图片，不使用拍照可以移除 -->
    <uses-permission android:name="android.permission.CAMERA" />
    <!-- 获取运营商信息，用于获取网络状态 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <!-- 获取读存储权限，用于附件等的获取 -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <!-- 访问 GPS 定位，用于定位消息，如果不用定位相关可以移除 -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <!-- 允许程序在手机屏幕关闭后后台进程仍然运行 -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <!-- 申请闹钟定时权限，SDK 心跳中使用，3.9.8及以后版本可以不添加 -->
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
    <!-- IM SDK required end -->

</manifest>

防止代码混淆

在 app/proguard-rules.pro 文件中添加如下行，防止混淆 SDK 的代码：

-keep class io.agora.** {*;}
-dontwarn  io.agora.**