Virtual Avatar
  • iOS : Objective-C
  • Android
  • Overview
  • Client SDKs
  • Demo app
  • Getting started
    • Integrate the SDK
    • Create a virtual avatar
    • ZegoCharacterHelper instructions
  • Guides
  • Best practice
  • Error codes
  • Server APIs

Integrate the SDK

Last updated:2022-12-23 13:03


Before you integrate the ZegoAvatar SDK, ensure that the development environment meets the following requirements:

  • Xcode 5.0 or later.
  • The iOS system is in version 11.0 or later and supports audio and video real iOS devices.
  • An real iOS device that is running on iOS 11 or later and supports audio and video.
  • The front camera and microphone of the device function normally.

Integrate the SDK

1. Optional: Create a project

Skip this step if a project already exists.
  1. Start Xcode. In the Welcome to Xcode window, select Create a new Xcode project or select File > New > Project. In the table form that is displayed, select the iOS platform, select Application > App, and click Next.
  1. Fill in the table form, select the desired options to configure a project, and click Next.

    Product Name and Organization Identifier must be provided to create the Bundle Identifier that identifies the app in the entire system.

  1. Select the project storage path and click Create to create a project.

2. Import the SDK

  1. Go to SDK Downloads to download the latest SDK version and decompress the SDK package after the download.

    ZEGOCLOUD provides the XCFramework SDK, which includes the ARM64 architecture and does not include the ARMv7 architecture.

  2. Manually copy the SDK dynamic library file ZegoAvatar.xcframework to the project directory.

  3. Open Xcode, select File > Add Files to "xxx" (xxx indicates the project name), and add the SDK Library file to the project.


  4. Select TARGETS > General > Frameworks,Libraries,and Embedded Content, add ZegoAvatar.xcframework, and set Embed to Embed & Sign.


  5. Select TARGETS > Build Settings > Build Options and set Enable Bitcode to NO.


3. Set permissions

Based on actual application needs, set permissions required by the application.

  1. In Xcode, select TARGETS > Info > Custom iOS Target Properties.
  1. Click the plus icon (+) and add the camera and microphone permissions.

    • Camera (used for the facial expression mirroring feature): Privacy - Camera Usage Description

    • Microphone (used for the speech simulation feature): Privacy - Microphone Usage Description

      AddPrivacy Done

Import resource packages

Before using AI capabilities provided by the ZegoAvatar SDK, you need to import the corresponding resource packages. Go to SDK Downloads to obtain the following resource packages.

You can import resource packages using the dynamic downloading or added from local method.

Resource name Description Package size Support
dynamic downloading
Recommended download time
AI model resources of the ZegoAvatar SDK. To use the facial expression mirroring, speech simulation, automatic avatar generation, or other capabilities, you need to transfer the absolute path of the resource to the ZegoAvatar SDK.
  • Facial expression mirroring: 8.2 MB
  • Speech simulation: 2.4 MB
  • Automatic avatar generation: 12.4 MB
Download the resource before the ZegoAvatarService SDK is initialized.
Aesthetics resources, including the basic 3D human model resources, resource mapping table, and default human model appearance.
  • Android: 13 MB
  • iOS: 14.4 MB
Download the resource before the ZegoCharacterHelper class is created.
Makeup, widget, accessory, and other resources.
Each resource is 200 KB to 1 MB in size, depending on the resource complexity.
We recommend that you download the related resources only when you need them to reduce the occupation of the local storage space.

Packages contain some aesthetic resources. Contact ZEGOCLOUD team to obtain all aesthetic resources if required.

Added from local

  1. Go to SDK Downloads to obtain related resource packages.

  2. Decompress obtained resource packages, find the assets folder, and drag and drop it to your project.


  3. In the dialog box that appears, select Create folder references to add the folder.


  4. The following figure shows the directory structure after the folder is added.