zego_effects_plugin 2.2.9

zego effects plugin is a flutter plugin for zego effects sdk

zego_effects_plugin

The AI Effects Flutter SDK provided by ZEGO is a Flutter Plugin Wrapper that is based on the native AI Effects SDK. It provides various AI-powered real-time video effects, including face beautification, AR effects, image segmentation, and more. You can use the ZegoEffects SDK for a wide range of use cases, such as social and entertainment live streaming, online education, and camera tools.

1️⃣ Install Flutter

Flutter Get Started

2️⃣ Set up the development environment

• Android Studio: Select the Preferences > Plugins, and search the Flutter plugin and install it, and add the Flutter SDK path downloaded in the previous step.

• VS Code: Search the Flutter extension in the application store and install it.

After setting up the Flutter environment, run the command flutter doctor, and install the dependency according to the instructions.

3️⃣ Apply for the ZEGO Effects license

You need to refer to the following document to get your license.

https://docs.zegocloud.com/article/12291

4️⃣ Import the zego_effects_plugin

Open the pubspec.yaml in your project and add the plugin dependency.

• Using pub（recommended）

dependencies:
  flutter:
    sdk: flutter

  zego_effects_plugin: ^2.2.9

Run the command flutter pub get after saving the file.

iOS: use Swift Package Manager (SPM)

Requirements

• Flutter 3.24 or later. This integration has been tested with Flutter 3.29.2 on a physical iPhone.
• Xcode with Swift 5.9 or later, also meeting the requirements of your Flutter version.
• iOS deployment target 12.0 or later.
• zego_effects_plugin 2.2.9 or later, containing ios/zego_effects_plugin/Package.swift. For local development, use this repository as a path dependency instead of the pub.dev dependency above:

dependencies:
  zego_effects_plugin:
    path: ../zego_effects_flutter_sdk # Relative to your app's pubspec.yaml.

Enable SPM and build

Run these commands from your Flutter application directory:

flutter config --enable-swift-package-manager
flutter pub get
flutter build ios --release --no-codesign

flutter config changes the Flutter SDK's global configuration. For a scoped build, the tested Flutter 3.29.2 toolchain also supports an environment override:

FLUTTER_SWIFT_PACKAGE_MANAGER=true flutter pub get
FLUTTER_SWIFT_PACKAGE_MANAGER=true flutter build ios --release --no-codesign

Flutter adds FlutterGeneratedPluginSwiftPackage to the Xcode project. The plugin's Package.swift then resolves the native effects-ios package at exactly 2.2.9 and downloads ZegoEffects.xcframework automatically. No manual ZIP download, checksum configuration, or Xcode package addition is required in a Flutter app. Do not add the same SDK again as a Pod or a local framework.

The podspec is retained for CocoaPods compatibility. Other plugins in the app may still use CocoaPods, so keep the Podfile and open ios/Runner.xcworkspace when using Xcode. Remove only manually added ZegoEffects Pod declarations or old local ZegoEffects.framework / ZegoEffects.xcframework references when migrating. See the Flutter SPM guide for automatic migration and troubleshooting.

Check the Xcode project after migration

After the first Flutter build, open ios/Runner.xcworkspace and check:

• Runner links FlutterGeneratedPluginSwiftPackage, whose local package path is ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage relative to the app.

• Product > Scheme > Edit Scheme > Build > Pre-actions contains Run Prepare Flutter Framework Script, with Provide build settings from set to Runner and this script:

  /bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare
  

• Every Scheme/Flavor used to build the app has the pre-action. Runner's deployment target is at least iOS 12.0 in every build configuration; keep the Podfile's platform :ios consistent if the app also uses CocoaPods.

Flutter normally adds the package and pre-action automatically. If migration fails, follow the manual integration steps in the linked Flutter SPM guide. Do not manually add effects-ios as a second package dependency: the plugin already declares it.

Run this repository's example

The example already uses the plugin through path: ../. From the repository root:

cd example
flutter config --enable-swift-package-manager
flutter pub get
flutter devices
flutter run --release -d <device-id>

Before running:

• If example/lib/zego_config.dart does not exist, create it from zego_config.dart.template in the same directory. Fill in your own AppID and AppSign. The local config file is ignored by Git; do not put real credentials in this README or the template.
• In Xcode, select your local signing team for Runner and use a Bundle ID authorized for your AppID. A --no-codesign build only checks compilation; installation requires a valid signing configuration.
• Allow camera access, then open Effects Camera and create the engine. This example uses release mode for physical-device verification.

Resources, permissions, and verification

SPM supplies the native SDK binary, not the models or effect resources. Add the required .model files and SDK resource bundles to Runner's Copy Bundle Resources, as in the example. The default setResources() implementation finds them in the main app bundle. Wait for resource registration before calling create(appID, appSign). Do not pass Backgrounds.bundle to setResources: it contains background images, not a SDK resource bundle with config.json.

Add NSCameraUsageDescription and, if requesting microphone access, NSMicrophoneUsageDescription to Info.plist. If using permission_handler through CocoaPods, ensure the permissions you request are enabled in its build macros (PERMISSION_CAMERA=1, PERMISSION_MICROPHONE=1), as in the example's Podfile.

To verify the integration:

• Xcode's package dependencies should resolve effects-ios to 2.2.9; this plugin and the native ZegoEffects SDK should not be resolved through CocoaPods when SPM is enabled.
• Confirm camera preview and beauty effects on a physical device. If Effects creation fails, the example shows the error code and falls back to the original camera preview. Error 5100006 means the Bundle ID does not match the authentication configuration; see the SDK error codes.
• The current XCFramework contains arm64 device and x86_64 simulator slices, but no arm64 simulator slice. Use a physical iPhone for verification on an Apple Silicon Mac; switching to SPM does not add simulator architectures.

5️⃣ Add permissions

Android

Open the file app/src/main/AndroidManifest.xml, and add the following:

<!-- SDK Needs Permission -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

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

iOS

Select the target project, click Info > Custom iOS Target Properties.

Click the + button to add camera and microphone permissions.

1. Privacy - Camera Usage Description

If you need to use the Platform View, and the Flutter version is lower than 1.22, you will need to add an additional line of description on your iOS device. For details, see FAQ-1

6️⃣ Initialize the SDK

import 'package:zego_effects_plugin/zego_effects_plugin.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
    String version = 'Unknown';

    @override
    void initState() {
        super.initState();
        initializeEffects();
    }

    Future<void> initializeEffects() async {
        // Supply your own credentials through a local, untracked configuration.
        const appID = int.fromEnvironment('ZEGO_APP_ID');
        const appSign = String.fromEnvironment('ZEGO_APP_SIGN');
        if (appID <= 0 || appSign.isEmpty) {
            throw StateError('Provide ZEGO_APP_ID and ZEGO_APP_SIGN');
        }

        // Models and resource bundles must be ready before creating Effects.
        await ZegoEffectsPlugin.instance.setResources();
        final errorCode = await ZegoEffectsPlugin.instance.create(appID, appSign);
        if (errorCode != 0 && errorCode != 5100000) {
            throw StateError('Effects creation failed: $errorCode');
        }

        final sdkVersion = await ZegoEffectsPlugin.instance.getVersion();
        if (mounted) setState(() => version = sdkVersion);
    }

    @override
    Widget build(BuildContext context) {
        return MaterialApp(home: Scaffold(
            appBar: AppBar(title: const Text('ZegoEffects')),
            body: Center(child: Text('Version: $version')),
        ));
    }
}

The snippet accepts credentials through Dart defines; provide your own AppID and AppSign when running it. The bundled example instead reads its local zego_config.dart. This only creates the SDK object. Before processing frames, call initEnv with the actual frame size. When using the example's Express custom-processing bridge, the native bridge initializes the environment from the captured frame dimensions.

7️⃣ Add colorful beauty effects

At present, only some beauty methods are exposed in the demo. You can add other beauty effects methods according to your real needs. The adding steps are as follows:

1. Add a method to zego_effects_plugin.dart
2. Add the implementation of this method in ZegoEffectsPlugin.java, and finally call the native method to complete.

You can refer to the android native documentation to add beauty effects.ZegoEffects Reference

8️⃣ FAQ

1. iOS: This error occurs when using Platform View: [VERBOSE-2:platform_view_layer.cc(28)] Trying to embed a platform view but the PaintContext does not support embedding.

This setting is no longer required for versions of Flutter 1.22 and later.

Open the iOS native project (Runner. Xcworkspace) that needs to use the Platform View, add the field io.flutter.embedded_views_preview to Info.plist, its value is YES.

2. iOS: fatal error: lipo: -extract armv7 specified but fat file: [...] does not contain that architecture

This issue usually occurs when switching iOS devices and can be resolved by removing the flutter-project-path/build/ and flutter-project-path/ios/DerivedData/ directories. (if you cannot find DerivedData folder, find /Users/your-user-name/Library/Developer/Xcode/DerivedData/ instead.)

3. iOS: The error occurs when compiling: CDN: trunk URL couldn't be downloaded or CDN: trunk Repo update failed

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

This is usually caused by a poor network, it is recommended to enable the agent. For details, see iOS CocoaPods - FAQ.

4. iOS: Black tearing crack occurs when previewing.

Please enable Platform View for rendering on the iOS Platform. Due to some known compatibility issues, rendering with Texture for preview using the Express SDK on the iOS Platform cannot achieve the desired effect temporarily. This issue will be fixed in the later version.

5. Android: When the Flutter was upgraded to V1.10 or later, NoClassDefFoundError appeared on the Android release causing the crash.

The Flutter has enabled code obfuscations by default in version 1.10 or later. Please add the -keep class configuration to the SDK in the app/proguard-rules.pro project to prevent obfuscations.

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

6. Android: The following crashes may occur when TextureRenderer is frequently created or destroyed.

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)

The cause of this issue is that the Flutter Engine caused thread insecurity when calling the updateTexImage() and release() of the SurfaceTexture, and this has been fixed in version 1.24-candidate.2. For details, see https://github.com/flutter/engine/pull/21777

7. For other questions, see Q&A