Avatar 虚拟形象
  • iOS : Objective-C
  • Android
  • Unity3D
  • 产品简介
  • 下载
  • 下载体验 App
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 创建虚拟形象
    • ZegoCharacterHelper 使用说明
  • 基本功能
  • 进阶功能
  • 最佳实践
  • 常见错误码
  • 客户端 API
  • 常见问题

创建虚拟形象

更新时间:2022-11-02 21:23

前提条件

在实现基本的 Avatar 功能之前,请确保:

  • 已在项目中集成了 Avatar SDK,详情请参考 集成 SDK
  • 已开启摄像头权限。

使用步骤

本节介绍如何使用 ZegoAvatar SDK 实现基本的图像处理功能,API 调用时序如下图:

1 申请鉴权

ZEGO Avatar 目前使用 在线鉴权 的方式获取 License 授权文件。

1.1 开通 ZegoAvatar 权限

  1. 请先在 ZEGO 控制台 创建项目,并申请有效的 AppID 和 AppSign,详情请参考 控制台 - 项目管理 中的“项目信息”。

  2. 请联系 ZEGO 商务人员,提供自己项目的 Bundle Id,开通相关权限。

1.2 获取参考代码

请将从 下载 获取到的示例源码中的 LicenseHelper 文件夹中的代码,拷贝到自己的项目下。

  1. 修改 ZegoAvatarConfig.h 文件,请使用已获取的 AppID 和 AppSign 正确填写,否则示例源码无法正常运行。

    // 鉴权服务器的地址
    static NSString *AVATAR_BASE_URL = @"https://aieffects-api.zego.im?Action=DescribeAvatarLicense";
    
    // 获取到的 AppID, APPID 跟 Bundle Id 有绑定关系,“Bundle Identifier” 设置为申请 AppID 时所提供的 Bundle Id
    static NSUInteger AVATAR_APPID = YOUR_APP_ID;
    
    // 获取到的 AppSign
    static NSString *AVATAR_APP_SIGN = YOUR_APP_SIGN;
  2. 在项目中,选择 “TARGETS > Signing & Capabilities” 菜单,将 “Bundle Identifier” 设置为申请权限时所提供的 Bundle Id。

1.3 安装依赖库

  1. 打开终端,进入项目根目录,执行 pod 'YTKNetwork',引入依赖库。

  2. 执行 pod install 命令安装依赖库。

1.4 获取 License

通过 ZGAvatarLicenseHelper 中的 requestLicense 接口,发起网络请求,获取鉴权 License 字符串。

// 发起网络请求获取 License
[ZGAvatarLicenseHelper requestLicense:^(NSString * _Nonnull license) {
    if (license.length > 0) {

        // 初始化 AvatarService
        [self initAvatarService: license];
    }
}];
获取 License 时,ZEGO 服务端返回信息及处理建议

发起请求时,ZEGO 服务端可能会返回的信息和处理建议如下:

参数名 类型 说明 处理建议
Code
unsigned int32
通过客户端发送请求时,ZegoAvatar 服务端返回的错误码,取值如下:

  • 0:成功。
  • 1:参数有误。
  • 2:Token 有误。
  • 3:证书无效。
  • 4:服务内部问题。
  • 1:请检查您的输入参数 AppID 是否正确, AuthInfo 是否为空。
  • 2:AuthInfo 获取不正确,请联系 ZEGO 技术支持处理。
  • 3:AppId 或者 Bundle ID 不正确、或不匹配。
  • 4:请联系 ZEGO 技术支持处理。
Message
string
返回的提示信息,和 “Code” 的取值相对应。

  • 0:Success
  • 1:Invalid argument
  • 2:Invalid token
  • 3:No valid license
  • 4:Service unavailable
Data
object
“Code” 为 0 时,Data 返回鉴权文件的内容;“Code ”返回其它值时,表示获取鉴权失败,Data 为空。
License
string
鉴权文件的内容。

2 初始化 AvatarService

  1. 初始化 AvatarService 之前,请先导入以下相关的头文件,准备基础工作。

    // 引入头文件
    #import <ZegoAvatar/ZegoAvatarService.h>
  2. 导入头文件后,调用 initWithConfig 接口,传入之前获取到的鉴权 License 字符串,初始化 AvatarService。

    // 初始化 AvatarService
    - (void) initAvatarService: (NSString*) license{
        // 创建 config
        ZegoServiceConfig *config = [[ZegoServiceConfig alloc] init];
        // 将获取到的 License 文件传入
        config.license = license;
        // 指定 AI 模型的路径
        config.AIPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/AIModel.bundle"];
        // 监听初始化状态,addServiceObserver 需要在 "主线程" 执行!!!
        [[ZegoAvatarService sharedInstance] addServiceObserver:self];
    
        // 初始化 AvatarService
        [[ZegoAvatarService sharedInstance] initWithConfig:config];
    }
  3. 注册 onStateChange 回调,接收初始化状态的相关回调通知。

    // AvatarService 初始化状态回调
    - (void)onStateChange:(ZegoAvatarServiceState)state {
        // SDK 初始化成功
        if (state == ZegoAvatarServiceState_InitSucceed) {
            // 初始化虚拟形象
            [self initAvatar];
        }
    }

3 创建虚拟形象

在创建虚拟人物形象时,为了简化 Character(虚拟人物形象)的初始化、序列化、数据缓存、路径拼接等功能的接入流程,ZEGO Avatar SDK 提供了 ZegoCharacterHelper 类(开源),帮助开发者快速创建人物虚拟形象,详情请参考 ZegoCharacterHelper 使用说明

初始化 AvatarService 后,通过创建 ZegoCharacterHelper 对象,传入虚拟人物形象的外观数据(捏脸、换装、妆容等),设置视图参数(宽、高、位置等),创建一个虚拟形象。

- (void) initAvatar{
    // 创建 Helper,传入基础资源的路径
    NSString *resourcePath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/base.bundle"];
    _characterHelper = [[ZegoCharacterHelper alloc] init:resourcePath];

    // 设置素材资源包地址,如果是动态下载,则传入下载的目标目录
    NSString *packagesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/Packages"];
    [_characterHelper setExtendPackagesPath:packagesPath];

    // 使用默认形象,以男性角色为例
    [_characterHelper setDefaultAvatar:MODEL_ID_MALE];

    // 创建 AvatarView
    _avatarView = [[ZegoAvatarService sharedInstance] createAvatarView:CGRectMake(0, 0, 200, 200)];
    [self.view addSubview:_avatarView];

    //角色上屏,请保证上屏之前设置过正确的 AvatarJson 数据,即调用过 setDefaultAvatar 或 setAvatarJson 方法。
    [_characterHelper setCharacterView:_avatarView];
}

如果用户不使用默认形象,想要根据图片自动生成定制化的虚拟形象,请参考 AI 捏脸

其它操作

虚拟形象创建完成后,可体验 Avatar 相关功能: