实时音视频
  • iOS
  • Android
  • macOS
  • Windows
  • HarmonyOS
  • Linux
  • Web
  • 小程序
  • Flutter : Dart
  • Electron
  • Unity3D
  • uni-app
  • React Native
  • Cocos Creator
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 实现视频通话
    • 实时音视频 SDK 与实时语音 SDK 差异
    • 场景化音视频配置
  • 基础功能
  • 进阶功能
  • 最佳实践
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

集成 SDK

更新时间:2023-01-04 16:48

1 准备环境

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

  • Flutter 1.12 或以上版本。
  • iOS 9.0 或以上版本,且支持音视频的 iOS 设备或模拟器(推荐使用真机)。
  • Android 4.4 或以上版本,且支持音视频的 Android 设备或模拟器(推荐使用真机)。如果为真机,请开启“允许调试”选项。
  • Windows 7 或以上版本(注意:目前 SDK 在 Windows 上仅支持音频功能,暂不支持视频功能)。
  • Web:Chrome 58 或以上版本、Firefox 56 或以上版本、Safari 11 或以上版本、Opera 45 或以上版本、QQ 浏览器 Windows 10.1 或以上版本/macOS 4.4 或以上版本、360 安全浏览器极速模式。
  • 设备已经连接到 Internet。

请配置开发环境如下:

  • Android Studio:“Preferences > Plugins”,搜索 “Flutter” 插件进行下载,并在插件中配置已经下载好的 Flutter 的 SDK 路径。
  • VS Code: 在应用商店中搜索 “Flutter” 扩展并下载。

以上任一开发环境配置好 Flutter 环境后,在终端执行 flutter doctor,根据提示内容补全相关未下载的依赖项。

Flutter SDK 支持开发 iOS、Android 和 Web 程序,但是 Web 的接口数量和集成方式与 iOS 和 Android 有一定区别,详细情况请参考 SDK 包 中 readme.md 文件。

2 集成 SDK

2.1 新建项目(可选)

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

请参考 Flutter 文档 - Get Started 创建一个 Flutter 项目。

2.2 导入 SDK

  1. 打开 “pubspec.yaml” 文件,添加 “zego_express_engine” 依赖,有以下两种形式:
  • 以 “pub” 形式依赖(推荐):

    dependencies:
    flutter:
    sdk: flutter
    
    zego_express_engine: ^2.0.0
  • 以 “git” 形式依赖:

    dependencies:
    flutter:
    sdk: flutter
    
    zego_express_engine:
      git:
        url: git@github.com:zegoim/zego-express-flutter-sdk.git
        ref: main
  1. 添加完成并保存文件后,在终端执行 flutter pub get

3 设置权限

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

3.1 Android 添加权限

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

如果在构建发行版 apk(flutter build apk)期间启用了混淆(默认启用),则需要配置与 ZEGO 相关的类,防止混淆,请参考 4 常见问题

<!-- Permissions required by the 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.CAMERA" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- Permissions required by the Demo App -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-feature android:glEsVersion="0x00020000" android:required="true" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

因为 Android 6.0 在一些比较重要的权限上要求必须申请动态权限,不能只通过 “AndroidMainfest.xml” 文件申请静态权限。请自行在 pub 上寻找第三方 flutter 插件来实现,或者在 Android 原生层参考执行如下代码,其中 “requestPermissions” 是 “Activity” 的方法。

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

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, "android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED ||
        ContextCompat.checkSelfPermission(this, "android.permission.RECORD_AUDIO") != PackageManager.PERMISSION_GRANTED) {
        requestPermissions(permissionNeeded, 101);
    }
}

具体的权限说明如下:

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

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

3.2 iOS 添加权限

打开项目,选择菜单 “TARGETS > Info > Custom iOS Target Properties”。

AddiOS Privacy

单击 “+” 按钮,添加摄像头和麦克风权限。

  • Privacy - Camera Usage Description

  • Privacy - Microphone Usage Description

权限添加完成后,如图所示:

AddiOS Privacy Done

如果使用 Platform View,并且 Flutter 版本低于 1.22,则需要为 iOS 添加其他说明,请参考 4 常见问题

4 常见问题

  1. iOS 平台使用 Platform View 时报错:“[VERBOSE-2:platform_view_layer.cc(28)] Trying to embed a platform view but the PaintContext does not support embedding”。

打开需要使用 Platform View 的 iOS 工程,在 “Info > Custom iOS Target Properties“ 中,增加字段 io.flutter.embedded_views_preview,并设置 “Value” 为 “YES”。

Flutter 1.22 或以上版本不再需要此设置。

iOS-Enable-PlatformView-Guide

  1. iOS 平台报错:“fatal error: lipo: -extract armv7 specified but fat file: [...] does not contain that architecture”。

通常在切换 iOS 设备时出现,可通过删除 “flutter-project-path/build” 和 “flutter-project-path/ios/DerivedData” 目录解决。(如果没有 “DerivedData” 文件夹,请查找 “/Users/your-user-name/Library/Developer/Xcode/DerivedData”)。

  1. iOS 平台编译时报错:“CDN: trunk URL couldn't be downloaded” 或者 “CDN: trunk Repo update failed”。

打开 Terminal 终端, cd 进项目根目录下的 "ios" 文件夹(“Podfile” 文件所在的目录),执行 pod repo update

该报错通常是由于国内网络不畅导致的,建议开启代理,请参考 CocoaPods 常见问题

  1. Android 平台 Flutter 升级至 v1.10 或以上版本时,Android release 下出现 “NoClassDefFoundError” 导致 Crash。

Flutter 在 1.10 或以上版本默认开启了混淆,请在 “app/proguard-rules.pro”文件中, 为 SDK 添加 “-keep” 类的配置防止混淆。

-keep class **.zego.**{*;}
  1. Android 平台当频繁创建和销毁 TextureRenderer 时,发生崩溃,报错如下:
OpenGLRenderer  E  [SurfaceTexture-0-4944-46] updateTexImage: SurfaceTexture is abandoned!
       flutter  E  [ERROR:flutter/shell/platform/android/platform_view_android_jni.cc(39)] java.lang.RuntimeException: Error during updateTexImage (see logcat for details)

该问题是由于在 Flutter Engine 内部调用 “SurfaceTexture” 的 “updateTexImage()” 和 “release()”时,线程不安全引起的。该问题已在Flutter 1.24-candidate.2 版本中修复。详细信息请参考 防止 SurfaceTexture.release 和 updateTexImage 之间的竞争