文档中心
实时语音
快速开始
集成 SDK

集成 SDK

更新时间：2025-04-11 11:22

1 准备环境

在开始集成 ZEGO Express SDK 前，请确保开发环境满足以下要求：

Android Studio 2020.3.1 或以上版本。

Android SDK 25、Android SDK Build-Tools 25.0.2、Android SDK Platform-Tools 25.x.x 或以上版本。
Android 4.4 或以上版本，且支持音视频的 Android 设备。
Android 设备已经连接到 Internet。

2 集成 SDK

2.1 （可选）新建项目

此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步。

打开 Android Studio，选择 “File > New > New Project” 菜单。
填写项目名及项目存储路径。
其它按照默认设置，单击 “Next”，最后单击 “Finish” 完成新工程创建。

2.2 导入 SDK

目前支持的平台架构包括：armeabi-v7a、arm64-v8a、x86、x86_64。

开发者可通过以下任意一种方式实现集成 SDK。

方式一：自动集成 SDK（推荐）

进入项目根目录，打开 “settings.gradle” 文件，在 “dependencyResolutionManagement” 中加入如下代码。

如果您在 “settings.gradle” 中找不到上述字段，可能是因为您的 Android Gradle Plugin 版本低于 v7.1.0。

相关信息请参考 Android Gradle Plugin Release Note v7.1.0。
```
...
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url 'https://storage.zego.im/maven' }
        google()
        mavenCentral()
    }
}
```
若您的 Android Gradle Plugin 版本低于 v7.1.0，请按照如下方式操作：

进入项目根目录，打开 “build.gradle” 文件，在 “allprojects” 中加入如下代码。
```
...
allprojects {
    repositories {
        maven { url 'https://storage.zego.im/maven' }
        google()
        mavenCentral()
    }
}
```
进入 “app” 目录，打开 “build.gradle” 文件，在 “dependencies” 中添加 implementation 'im.zego:express-audio:x.y.z'，请从发布日志查询 SDK 最新版本，并将 x.y.z 修改为具体的版本号。
```
...
dependencies {
    ...
    implementation 'im.zego:express-audio:x.y.z'
}
```

方式 2：复制 SDK AAR 文件手动集成

复制 SDK AAR 文件手动集成

请参考下载文档，下载最新版本的 SDK 并解压。
将解压后的 AAR 文件中的 “release/Library/ZegoExpressEngine.aar” 文件拷贝至您的项目目录下，如 “app/libs”。
SDK 包中的 “release/Library/” 目录下的文件包含：
- “.aar” 文件：供您在采用本集成方式时使用，其他文件可以忽略。
- 其他文件：供您在采用方式 3：复制 SDK JAR + SO 文件手动集成使用。
进入项目根目录，打开 “settings.gradle” 文件，在 “dependencyResolutionManagement” 中加入如下代码。
```
...
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        flatDir {
            dir 'app/libs'
        }
    }
}
```
如果您在 “settings.gradle” 中找不到上述字段，可能是因为您的 Android Gradle Plugin 版本低于 v7.1.0，相关信息请参考 Android Gradle Plugin Release Note v7.1.0。此时请按照如下方式操作：

进入项目根目录，打开 “build.gradle” 文件，在 “allprojects” 中加入如下代码。
```
...
allprojects {
    repositories {
        google()
        mavenCentral()
        flatDir {
            dir 'app/libs'
        }
    }
}
```
进入 “app” 目录，打开 “build.gradle” 文件，在 “dependencies” 中添加 implementation(name: 'ZegoExpressEngine', ext: 'aar')。
```
...
dependencies {
    ...
    implementation(name: 'ZegoExpressEngine', ext: 'aar')
}
```
并在 “defaultConfig” 节点添加 “ndk” 节点，指定支持的架构。
```
ndk {
    abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
}
```
根据实际情况决定要支持的架构。通常在发布 App 时只需要保留 "armeabi-v7a" 和 "arm64-v8a" 即可，可以减少 APK 包大小。

方式 3：复制 SDK JAR + SO 文件手动集成

复制 SDK JAR + SO 文件手动集成

请参考下载文档，下载最新版本的 SDK 并解压。
将解压后的 “release/Library/” 目录下的 “其他文件（除 .aar 文件之外）” 拷贝至您的项目目录下，如 “app/libs”。
- 架构目录下的 “include” 目录是 SDK 的 C++ 头文件，如果您仅使用 Java 接口进行开发，可以忽略。
- “ZegoExpressEngine-sources.jar” 是源码包，您可在 Android Studio 导入，以获得更好的开发体验，详情请参考 Express Android SDK 如何查看 API 注释和文档？
添加 SDK 引用，打开 “app” 目录下的 “build.gradle” 文件。
1. 在 “defaultConfig” 节点添加 “ndk” 节点，指定支持的架构。
```
ndk {
    abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
}
```
  根据实际情况决定要支持的架构。通常在发布 App 时只需要保留 "armeabi-v7a" 和 "arm64-v8a" 即可，可以减少 APK 包大小。
2. 在 “android” 节点添加 “sourceSets” 节点，指定 “libs” 所在目录。
  
  示例代码中 “libs” 目录仅为举例，开发者可根据实际路径填写。
```
sourceSets {
    main {
        jniLibs.srcDirs = ['libs']
    }
}
```
3. 在 “dependencies” 节点引入 “libs” 下所有的 jar。
```
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    ......
}
```

3 设置权限

根据实际应用需要，设置应用所需权限。

进入 “app/src/main” 目录，打开 “AndroidManifest.xml” 文件，添加权限。

<!-- SDK 必须使用的权限 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- App 需要使用的部分权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />

因为 Android 6.0 在一些比较重要的权限上要求必须申请动态权限，不能只通过 “AndroidMainfest.xml” 文件申请静态权限。因此还需要参考执行如下代码，其中 “requestPermissions” 是 “Activity” 的方法。
关于 BLUETOOTH 权限：仅 Android 6.0 以下版本需要声明，Android 6.0 及以上版本无需声明。

String[] permissionNeeded = {
    "android.permission.RECORD_AUDIO"};

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, "android.permission.RECORD_AUDIO") != PackageManager.PERMISSION_GRANTED) {
        //101 为 requestCode，可以是任何大于 0 的数字，会透传到权限请求结果回调 onRequestPermissionsResult
        requestPermissions(permissionNeeded, 101);
    }
}

具体的权限说明如下：

必要性	权限	权限说明	申请原因
必要权限	INTERNET	访问网络权限。	SDK 基本功能都需要在联网的情况下才可以使用。
	ACCESS_WIFI_STATE	获取当前 WiFi 状态权限。	SDK 会根据网络状态的改变执行不同的操作。例如当网络重连的时候，SDK 内部会将网络断开时的状态都恢复，用户不需做额外的操作。
	ACCESS_NETWORK_STATE	获取当前网络状态权限。
	RECORD_AUDIO	录制音频权限。	发送音频的时候需要使用该权限。
	BLUETOOTH	连接蓝牙设备权限。	连接蓝牙设备时需要使用该权限。关于 BLUETOOTH 权限：仅 Android 6.0 以下版本需要声明，Android 6.0 及以上版本无需声明。
	MODIFY_AUDIO_SETTINGS	修改音频配置权限。	修改音频设备配置时需要使用该权限。
非必要权限	READ_PHONE_STATE	允许以只读方式访问电话状态，包括当前的呼叫状态。	SDK 会根据当前的呼叫状态，启停音频设备。如监听到当前为呼叫状态，则 SDK 会自动停止使用音频设备，直到通话结束。
非必要权限	WRITE_EXTERNAL_STORAGE	内置 SDK 写权限。	若需要使用媒体播放器或音效播放器加载 Android 外部存储内的媒体资源文件，则需要申请此权限，否则 SDK 无法加载资源。

其中非必要权限 “android.permission.READ_PHONE_STATE” 仅用于实现 SDK 的打断事件处理，因此只需在 AndroidMainfest.xml 文件中进行声明即可，不需要动态申请（业务方有需求则另外处理）。

4 防止混淆代码

在 “proguard-rules.pro” 文件中，为 SDK 添加 -keep 类的配置，防止混淆 SDK 公共类名称。

-keep class **.zego.**{*;}