logo
ConsoleSign Up
Document
Client API
Server API
Video Call
Flutter: Dart
Introduction
Overview
Product Features
Differences Between Video Call SDK and Voice Call SDK
Client SDK
Download SDK
Release Notes
Upgrade Guide
Common Error Codes
Quick Start
Running Example Code Guide
Integrate the SDK
Implementing Video Call
Scenario-based Audio and Video Configuration
Connect to ZEGOCLOUD Document MCP Serverlink
Communication
Room Features
Audio
Video
Live Streaming
Other Features
Best Practices
FAQ
On this page

Integrate the SDK

2026-03-05

Prepare environment

Before integrating the ZEGO Express SDK, ensure that your development environment meets the following requirements:

  • Flutter 2.0 or above.
  • iOS 12.0 or above, with an iOS device or simulator that supports audio and video (using a real device is recommended).
  • Android 4.4 or above, with an Android device or simulator that supports audio and video (using a real device is recommended). If using a real device, enable the "Allow Debugging" option.
  • Windows 8 or above.
  • macOS 10.14 or above.
  • Web: Chrome 58 or above, Firefox 56 or above, Safari 11 or above, Opera 45 or above, QQ Browser: Windows 10.1 or above/macOS 4.4 or above, 360 Secure Browser Speed Mode.
  • Linux: Debian 10 or above, Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS.
  • The device is connected to the Internet.

Please configure the development environment as follows:

  • Android Studio: "Preferences > Plugins", search for the "Flutter" plugin to download, and configure the downloaded Flutter SDK path in the plugin.
  • VS Code: Search for the "Flutter" extension in the app store and download it.

After configuring the Flutter environment in any of the above development environments, run flutter doctor in the terminal, and complete the relevant undownloaded dependencies according to the prompts.

Note

Flutter SDK supports developing iOS, Android, Windows, macOS, and Web programs, but the number of interfaces and integration methods for Web are somewhat different from other platforms. For details, please refer to the README.md file in the SDK package.

Integrate the SDK

Create a new project (optional)

Please refer to Flutter Documentation - Get Started to create a Flutter project.

Import the SDK

  1. Open the "pubspec.yaml" file and add the "zego_express_engine" dependency. There are two ways:

    • Method 1: Depend on "pub" form (recommended):
    dependencies:
  flutter:
  sdk: flutter

  zego_express_engine: ^3.10.3
Note

The version number in the above code is only an example and not the latest version. For the latest version number, please refer to Download.

  • Method 2: Depend on "git" form:
dependencies:
  flutter:
  sdk: flutter

  zego_express_engine:
    git:
      url: git@github.com:zegoim/zego-express-flutter-sdk.git
      ref: main
  1. After adding and saving the file, run flutter pub get in the terminal.

Set up permissions

Set the permissions required by the application according to actual needs.

Add permissions for Android

Go to the "app/src/main" directory, open the "AndroidManifest.xml" file, and add permissions.

Note

If obfuscation is enabled during the release APK build (flutter build apk) (enabled by default), you need to configure ZEGOCLOUD-related classes to prevent obfuscation. Please refer to FAQ.

<!-- 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" />

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

Since Android 6.0 requires dynamic permissions for some important permissions, you cannot only apply for static permissions through the "AndroidMainfest.xml" file. Please find a third-party flutter plugin on pub to implement it, or refer to the following code in the Android native layer, where "requestPermissions" is a method of "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);
    }
}

The specific permission descriptions are as follows:

NecessityPermissionPermission DescriptionReason for Application
Required permissionsINTERNETAccess network permission.SDK basic functions need to be used when connected to the network.
ACCESS_WIFI_STATEGet current WiFi status permission.The SDK will perform different operations based on changes in network status. For example, when the network is reconnected, the SDK will restore all states when the network was disconnected internally, and users do not need to perform additional operations.
ACCESS_NETWORK_STATEGet current network status permission.
CAMERAAccess camera permission.When previewing and sending video, this permission is required.
RECORD_AUDIORecord audio permission.When sending audio, this permission is required.
BLUETOOTHConnect Bluetooth device permission.When connecting to a Bluetooth device, this permission is required.
MODIFY_AUDIO_SETTINGSModify audio configuration permission.When modifying audio device configuration, this permission is required.
Optional permissionsREAD_PHONE_STATEAllow read-only access to phone status, including current call status.The SDK will start and stop audio devices based on the current call status. If a call status is detected, the SDK will automatically stop using audio devices until the call ends.
WRITE_EXTERNAL_STORAGEBuilt-in SDK write permission.If you need to use the media player or sound effect player to load media resource files in Android external storage, you need to apply for this permission, otherwise the SDK cannot load resources.
Note

The optional permission "android.permission.READ_PHONE_STATE" is only used to implement the SDK's interrupt event handling, so it only needs to be declared in the AndroidMainfest.xml file and does not need to be applied dynamically (if the business side has requirements, handle it separately).

Add permissions for iOS

  1. Open the project, select "TARGETS > Info > Custom iOS Target Properties".

  2. Click the "+" button to add camera and microphone permissions.

  • Privacy - Camera Usage Description

  • Privacy - Microphone Usage Description

  1. After adding permissions, as shown in the figure:

Note

If you use Platform View and the Flutter version is lower than 1.22, you need to add other descriptions for iOS. Please refer to FAQ.

Import JavaScript SDK (for Web)

In index.html, use the <script> tag to import ZegoExpressWebFlutterWrapper.js from the /assets/packages/zego_express_engine directory in the ZEGO Express SDK for Flutter package.

Example code:

<!-- <your-project>/web/index.html -->
<!DOCTYPE html>
<html>
...
<body>
  ...
  <script type="application/javascript" src="assets/packages/zego_express_engine/assets/ZegoExpressWebFlutterWrapper.js"></script>
  ...
</body>
</html>

FAQ

  1. iOS platform error: "fatal error: lipo: -extract armv7 specified but fat file: [...] does not contain that architecture", how to handle?

    Usually occurs when switching iOS devices, can be solved by deleting the "flutter-project-path/build" and "flutter-project-path/ios/DerivedData" directories. (If there is no "DerivedData" folder, please look for "/Users/your-user-name/Library/Developer/Xcode/DerivedData").

  2. iOS platform compilation error: "CDN: trunk URL couldn't be downloaded" or "CDN: trunk Repo update failed", how to handle?

    Open Terminal, cd into the "ios" folder under the project root directory (where the "Podfile" file is located), and run pod repo update.

    This error is usually caused by poor domestic network. It is recommended to enable a proxy. Please refer to CocoaPods FAQ.

  3. "NoClassDefFoundError" occurs on Android release causing Crash, how to handle?

    Flutter enables obfuscation by default in version 1.10 or above. Please add "-keep" class configuration for the SDK in the "app/proguard-rules.pro" file to prevent obfuscation.

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

  4. When frequently creating and destroying TextureRenderer on the Android platform, a crash occurs with the following error, how to handle?

    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)

    This problem is caused by thread insecurity when calling "updateTexImage()" and "release()" of "SurfaceTexture" inside the Flutter Engine. This problem has been fixed in Flutter 1.24-candidate.2. For details, please refer to Prevent race between SurfaceTexture.release and updateTexImage.

  5. iOS platform build error: "[!] Unable to install vendored xcframework 'ZegoExpressEngine' for Pod 'zego_express_engine', because it contains both static and dynamic frameworks.", how to handle?

    1. First, please check the local CocoaPods version. If you are using Xcode 14.0 or higher, you must use CocoaPods 1.12.0 or higher. If the CocoaPods version is too low, please upgrade to the latest version to solve this problem.

    2. If it still cannot be solved, it may be because when the locally dependent SDK package is decompressed, the soft links in the native iOS xcframework used in the SDK package are lost, and the soft links become files. You can check whether the following files in the locally dependent SDK package are soft links. If they are not soft links, this problem will occur. You can try a different decompression method.

      • ios/libs/ZegoExpressEngine.xcframework/ios-arm64_x86_64-maccatalyst/ZegoExpressEngine.framework/Headers
      • ios/libs/ZegoExpressEngine.xcframework/ios-arm64_x86_64-maccatalyst/ZegoExpressEngine.framework/Modules
      • ios/libs/ZegoExpressEngine.xcframework/ios-arm64_x86_64-maccatalyst/ZegoExpressEngine.framework/Resources
      • ios/libs/ZegoExpressEngine.xcframework/ios-arm64_x86_64-maccatalyst/ZegoExpressEngine.framework/ZegoExpressEngine

Previous

Running Example Code Guide

Next

Implementing Video Call

On this page

Back to top