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

Create a virtual avatar

Last updated:2022-12-23 13:03


Before you implement basic avatar features, ensure that the following conditions are met:

  • The ZegoAvatar SDK is integrated into the project. For more information, see Integrate the SDK.
  • The camera permission is enabled.

Implementation steps

1. Apply for authentication

Virtual Avatar uses online authentication to obtain the license file.

1.1 Enable the ZegoAvatar permission

  1. Create a project in the ZEGOCLOUD Admin Console and get the AppID and AppSign of your project.
  2. Contact ZEGOCLOUD technical support and provide the Bundle ID of your project to enable related permissions.

1.2 Obtain the reference code

Copy code in the LicenseHelper folder of the sample source code obtained from SDK downloads to your project.

  1. Modify the ZegoAvatarConfig.h file. Enter the obtained AppID and AppSign correctly. Otherwise, the sample source code cannot run.

    // The address of the authentication server.
    static NSString *AVATAR_BASE_URL = @"";
    // The AppID get from ZEGOCLOUD. The AppID is bound to the Bundle ID. Set Bundle Identifier to the Bundle ID provided during AppID application.
    static NSUInteger AVATAR_APPID = YOUR_APP_ID;
    // The AppSign get from ZEGOCLOUD.
  2. In the project, go to TARGETS > Signing & Capabilities and set Bundle Identifier to the Bundle ID provided during AppID application.

1.3 Install dependency libraries

  1. Open the terminal, visit the root directory of the project, and run pod 'YTKNetwork' to introduce the dependency libraries.
  2. Run pod install to install the dependency libraries.

1.4 Obtain the license

Initiate a network request by using the requestLicense API in ZGAvatarLicenseHelper to obtain the authentication license.

// Initiate a network request to obtain the license.
[ZGAvatarLicenseHelper requestLicense:^(NSString * _Nonnull license) {
    if (license.length > 0) {
        /// Initialize ZegoAvatarService.
        [self initAvatarService: license];
When a request is initiated, the ZEGOCLOUD server may return the following information and suggestions:
Parameter Type Description Suggestion
unsigned int32
When a request is sent through the client, the ZegoAvatar server returns an error code with the following values:

  • 0: Succeed.
  • 1: Invalid parameter.
  • 2: Token is incorrect.
  • 3: Invalid certificate.
  • 4: Internal server error.
  • 1: Check your input AppID and AuthInfo.
  • 2: The obtained AuthInfo is incorrect. Please contact ZEGOCLOUD Technical Support.
  • 3: The AppID or Bundle ID is incorrect, authentication expired.
  • 4: Please contact ZEGOCLOUD Technical Support.
The displayed message corresponds to the value of "Code".

  • 0: Success
  • 1: Invalid argument
  • 2: Invalid token
  • 3: No valid license
  • 4: Service unavailable
Returned "Code" is 0: The content of the authentication file. Returned "Code" isn't 0: Authentication failed, data is empty.
Content of the authentication file.

2. Initialize AvatarService

  1. Before you initialize the AvatarService, import the header file:

    // Import header file.
    #import <ZegoAvatar/ZegoAvatarService.h>
  2. After the header files are imported, call the initWithConfig method and introduce the obtained authentication license to initialize the AvatarService.

    // Initialize AvatarService.
    - (void) initAvatarService: (NSString*) license{
        /// Create config.
        ZegoServiceConfig *config = [[ZegoServiceConfig alloc] init];
        // Import the obtained license file.
        config.license = license;
        // Specify the AI model storage path.
        config.AIPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/AIModel.bundle"];
        // Listen for the initialization status. Run addServiceObserver on the main thread.
        [[ZegoAvatarService sharedInstance] addServiceObserver:self];
        // Initialize ZegoAvatarService.
        [[ZegoAvatarService sharedInstance] initWithConfig:config];
  3. Listen for the onStateChange callback to receive related event notifications for the initialization status.

    // avatarService initialization status callback.
    - (void)onStateChange:(ZegoAvatarServiceState)state {
        // SDK initialized.
        if (state == ZegoAvatarServiceState_InitSucceed) {
            // Initialize the virtual avatar.
            [self initAvatar];

3. Create a virtual avatar

To simplify the integration process of the initialization, serialization, data caching, and path splicing features during virtual avatar creation, Virtual Avatar SDK provides the open-source ZegoCharacterHelper class to help you create virtual avatars quickly. For more information, see ZegoCharacterHelper instructions.

After the AvatarService is initialized, create a ZegoCharacterHelper object, introduce the appearance data of the virtual avatar, such as the facial features, clothing materials, and makeup, and set view parameters, such as the width, height, and position, to create a virtual avatar.

- (void) initAvatar{
    // Create a ZegoCharacterHelper class and introduce the basic resource path.
    NSString *resourcePath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/base.bundle"];
    _characterHelper = [[ZegoCharacterHelper alloc] init:resourcePath];

    // Set the resource package address. If resources are downloaded dynamically, introduce the target directory for downloading.
    NSString *packagesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/Packages"];
    [_characterHelper setExtendPackagesPath:packagesPath];

    // Use the default avatar. The male role is used as an example.
    [_characterHelper setDefaultAvatar:MODEL_ID_MALE];
    /// Create AvatarView.
    _avatarView = [[ZegoAvatarService sharedInstance] createAvatarView:CGRectMake(0, 0, 200, 200)];
    [self.view addSubview:_avatarView];
    // Display the avatar on the screen.
    [_characterHelper setCharacterView:_avatarView];

If you do not want to use the default avatar and want to customize a virtual avatar based on the image, see Automatic avatar generation.