使用说明
本文介绍如何在你的项目中集成和使用虹图人像 3D 特效系列插件。
技术原理
虹图人像 3D 特效系列插件是对虹图 HTAvatar 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor
方法,传入指定的 key
和 value
参数,你可以快速集成虹图的人像 3D 特效能力。
setExtensionPropertyWithVendor
方法的 key
参数与虹图的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用该方法时只要传入指定的 key
和 value
,就可以调用对应的虹图 API,实现人像 3D 特效的有关功能。
前提条件
iOS 开发环境需满足以下要求:
- Xcode 10.0 或以上版本。
- 运行 iOS 10.0 或以上版本的真机(非模拟器)。
示例项目
虹图人像 3D 特效系列插件提供了 Gitee 示例项目,你可以前往克隆或下载并进行体验。
平台 | 语言 | 示例代码 |
---|---|---|
Android | Java | AgoraHTAvatorExtensionDemo/Android |
iOS | Objective-C | AgoraHTAvatorExtensionDemo/iOS |
运行步骤
参考以下步骤快速跑通示例项目:
-
克隆仓库:
Shellgit clone https://gitee.com/htai-open/agora-htavatar-extension-demo.git
-
下载虹图人像 3D 特效系列的 iOS 插件包。解压后,将所有
.framework
库文件保存到iOS/ExtensionExample
。 -
联系声网获取证书文件和资源包。
-
将获取的证书文件
HTKey.h
和资源包HTEffect.bundle
保存到iOS/ExtensionExample
路径。 -
在终端中进入
agora-htavatar-extension-demo/iOS
目录,运行以下命令使用 CocoaPods 安装依赖:Shellpod install
-
在 Xcode 中打开项目
ExtensionExample.xcworkspace
。 -
打开
Config.h
,进行如下修改:-
将
<YOUR_APP_ID>
替换为你的声网 App ID。获取 App ID 请参考开通服务。 -
token
在运行 demo 时不必填写。Config.hObjective-CNSString *const appID = @"<YOUR_APP_ID>";
NSString *const token = nil;
-
-
打开
iOS/ExtensionExample/HTKey.h
,将<YOUR_HT_SDK_KEY>
替换为在声网购买的由虹图提供的测试 key:HTKey.hObjective-CNSString *const HTKey = @"<YOUR_HT_SDK_KEY>";
-
连接一台 iOS 真机(非模拟器),运行项目。
预期效果
运行成功后,示例项目会安装到你的 Android 或 iOS 设备上。
- 启动 App 后,虹图人像 3D 特效系列默认开启。你可以在界面上看到 enableExtension、htARSetModel 按钮。
- 点击 htARSetModel 设置 3D AR 道具效果。默认是拳击头套效果。目前 3D 不支持横屏适配。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网视频 SDK 和虹图人像 3D 特效系列插件。
1.1 使用声网 SDK 实现音视频互动
插件需要与 RTC SDK 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动:
1.2 购买和激活插件
你需要进入声网控制台 > 云市场页面,按照提示购买虹图人像 3D 特效系列插件。购买后需要保存好获取的证书文件,用于后续初始化插件。
1.3 集成插件
参考以下步骤集成插件:
-
下载虹图人像 3D 特效系列的 iOS 插件包。
-
解压文件夹,将所有
.framework
库文件保存到你的项目文件夹下。 -
将证书文件
HTKey.h
保存到项目文件夹下。 -
联系声网获取虹图人像 3D 特效系列的资源包,将
HTEffect.bundle
保存到项目文件夹下。 -
在 Xcode 中添加动态库,确保 Embed 属性设置为 Embed & Sign。
-
导入需要用到的头文件:
Objective-C#import <AgoraRtcKit/AgoraRtcEngineKit.h>
#import "HTKey.h" -
程序启动时在
main.m
中添加以下代码。Objective-C#import "AppDelegate.h"
#import <HTEffectAR/HTEffectARInterface.h>
int main(int argc, char * argv[]) {
[[HTEffectARInterface shareInstance] initRuntime:argc argv:argv];
NSString * appDelegateClassName;
@autoreleasepool {
// Setup code that might create autoreleased objects goes here.
appDelegateClassName = NSStringFromClass([AppDelegate class]);
}
return UIApplicationMain(argc, argv, nil, appDelegateClassName);
}
1.4 升级插件
声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。
以下是用 SQLite 来进行插件版本管理的示例:
- 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
- 每次项目初始化时,自动检测当前项目使用的资源包版本:
- 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。
- 如果记录的资源包版本与当前匹配,则正常实现业务。
如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。
以下升级流程以相芯美颜特效插件为例:
-
参考集成插件章节下载所需平台最新版本的插件包和资源包。
-
删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
-
删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。
编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。
2. 启用插件
初始化 AgoraRtcEngineKit
时,调用 enableExtensionWithVendor
启用插件。
[self.agoraKit enableExtensionWithVendor:@"Texeljoy"
extension:@"HTAvatar"
enabled:self.enable];
3. 初始化插件
初始化插件需要调用 setExtensionPropertyWithVendor
并传入对应的 key
和 value
进行离线鉴权。
- (void)initExtension{
// 资源拷贝
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARCopyResource"
value:[self toJson:@{
@"path":[[NSBundle mainBundle] pathForResource:@"HTEffect" ofType:@"bundle"]
}]];
// 离线鉴权方式
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARInitOffline"
value:[self toJson:@{
@"license":HTSDKKey
}]];
// (可选)设置图片格式
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARImageFormat"
value:[self toJson:@{
@"imageFormat":@5
}]];
}
4. 设置 3D AR 效果
设置 3D AR 效果需要调用 setExtensionPropertyWithVendor
并传入对应的 key
和 value
,具体顺序如下:
- 传入
key
为htARRenderEnable
,开启 AR 特效。 - 传入
key
为htARSetModel
,设置 AR 模型。
你可以参考示例项目,根据场景需要进行组合调用。