集成 SDK

---

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，根据提示内容补全相关未下载的依赖项。

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

2. 添加完成并保存文件后，在终端执行 flutter pub get。

3 设置权限

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

3.1 Android 添加权限

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

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

具体的权限说明如下：

3.2 iOS 添加权限

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

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

• Privacy - Camera Usage Description

• Privacy - Microphone Usage Description

权限添加完成后，如图所示：

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 或以上版本不再需要此设置。

2. 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”）。

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

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

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

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

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

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

5. 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 之间的竞争。