ZEGO Avatar
  • iOS : Objective-C
  • Android
  • Overview
  • Client SDKs
  • Demo app
  • Getting started
    • Integrate the SDK
    • Create a virtual avatar
    • ZegoCharacterHelper instructions
  • Guides
  • Error codes
  • API Documents
  • FAQ

Create a virtual avatar

Last updated:2022-06-29 12:12


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

ZEGO 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 of your project.
  2. Contact ZEGOCLOUD technical support and provide the AppID you get, the Bundle ID of your project, and the AppSign required for authentication 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 = @"https://aieffects-api.zego.im?Action=DescribeAvatarLicense";
    // 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];

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 a 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, ZEGO 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.