使用说明

本文介绍如何在你的项目中集成和使用火山引擎智能美化特效插件。

技术原理

火山引擎智能美化特效插件是对火山引擎 AI 开放平台 CV SDK 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor 方法，传入指定的 key 和 value 参数，你可以快速集成火山引擎的美化特效能力。

setExtensionPropertyWithVendor 方法的 key 参数与火山引擎的 API 名称完全对应，value 参数以 JSON 格式包装该 API 的部分或全部参数。因此，调用该方法时只要传入指定的 key 和 value，就可以调用对应的火山引擎 API，实现美化特效的有关功能。

前提条件

iOS 开发环境需满足以下要求：

• Xcode 9.0 或以上版本。
• 运行 iOS 8.0 或以上版本的真机（非模拟器）。

示例项目

火山引擎智能美化特效插件提供了 GitHub 示例项目，你可以前往克隆或下载并进行体验。

平台	语言	示例代码
Android	Java	ByteDance/android
iOS	Objective-C	ByteDance/ios

运行步骤

参考以下步骤快速跑通示例项目：

1. 克隆仓库：

   Shell

   git clone https://github.com/AgoraIO-Community/AgoraMarketPlace.git

2. 进入声网控制台 > 云市场 >火山引擎智能美化特效页面，点击下载 iOS 插件包，然后点击联系我们获取专属的证书文件（.licbag）。

3. 点击下载火山引擎智能美化特效插件的素材包，将所有文件保存到 ByteDance/ios/Resource 路径。素材包中提供的文件详见素材包结构说明。

4. 将你的证书文件（.licbag）保存在 ByteDance/ios/Resource/LicenseBag.bundle 路径下。

5. 在终端中进入 ByteDance/ios 目录，运行以下命令使用 CocoaPods 安装依赖：

   Shell

   pod install

6. 在 Xcode 中打开项目 ByteDance/ios/ExtensionExample.xcworkspace。

7. 解压下载的 iOS 插件包，将所有 .framework 文件导入项目，并将 Embed 修改为 Embed & Sign。

   

8. 打开 AppID.m 文件，进行如下修改：

   • 将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开通服务。
   • 将 <YOUR_LICENSE_NAME> 替换为你的证书文件名称。例如：证书文件为 bytedance_4.2.3.licbag，则在这里填入 bytedance_4.2.3.licbag。
   Objective-C

   NSString *const appID = <#YOUR_APP_ID#>;
   NSString *const token = nil;
   NSString *const license_name = <#YOUR_LICENSE_NAME#>;

9. 连接一台 iOS 真机（非模拟器），运行项目。

预期效果

运行成功后，示例项目会安装到你的设备上。按照如下步骤体验美化特效功能：

1. 启动 App 后，火山美颜插件默认开启。你可以在界面上看到 disableExtension 、 initExtension 、setComposer 和 setSticker 按钮。
2. 在界面上进行以下操作：
   • 点击 setComposer 设置滤镜。
   • 点击 setSticker 设置装扮贴纸。

集成和调用流程

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网视频 SDK 和火山引擎智能美化特效插件。

1.1 使用声网 SDK 实现音视频互动

插件需要与 RTC SDK 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动：

实现音视频互动

1.2 购买和激活插件

你需要进入声网控制台 > 云市场页面，按照提示购买火山引擎智能美化特效插件。随后你会收到专属的证书文件，用于后续初始化插件时进行鉴权。

1.3 集成插件

参考以下步骤集成插件：

1. 在项目文件夹下新建 Resource 文件夹，位置如下：

   Shell

   .
   ├── <ProjectName>
   ├── <ProjectName>.xcodeproj
   │   ├── project.pbxproj
   │   ├── project.xcworkspace
   │   └── xcshareddata
   └── Resource

2. 进入声网控制台 > 云市场页面下载火山引擎智能美化特效的 iOS 包。

3. 解压文件夹，将所有 .framework 包保存到 <ProjectName> 路径下。

4. 点击下载火山引擎智能美化特效插件的素材包，保存到 Resource 路径下。素材包中提供的文件详见素材包结构说明。

5. 导入需要用到的头文件：

   Objective-C

   #import <AgoraRtcKit/AgoraRtcEngineKit.h>
   #import "BDResourceHelper.h"

1.4 升级插件

声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理，从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时，会出现 App 闪退、崩溃等现象。

以下是用 SQLite 来进行插件版本管理的示例：

1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
2. 每次项目初始化时，自动检测当前项目使用的资源包版本：
   • 如果无记录文件或记录的资源包版本为旧，则更新资源。成功更新后，回写最新资源包版本信息到 SQLite。
   • 如果记录的资源包版本与当前匹配，则正常实现业务。

如果你的项目已经集成过声网云市场提供的第三方插件，并需要更新插件，可以参考以下步骤来保证更新后的可用性。

以下升级流程以相芯美颜特效插件为例：

1. 参考集成插件章节下载所需平台最新版本的插件包和资源包。

2. 删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。

3. 删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

注意

编译 App 时，系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行，否则可能会出现插件版本与资源包不匹配的情况，从而导致各种意外问题。

2. 启用插件

初始化 AgoraRtcEngineKit 时，调用 enableExtensionWithVendor 启用插件。

Objective-C

AgoraRtcEngineConfig *config = [AgoraRtcEngineConfig new];
// 监听插件事件，用于接收 onEvent 回调
config.eventDelegate = self;
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:config
                                                 delegate:self];
// 开启插件
[self.agoraKit enableExtensionWithVendor:@"ByteDance"
                               extension:@"Effect"
                                 enabled:self.enable];

3. 初始化插件

初始化插件需要调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value，具体顺序如下：

1. 检查授权。对应的 key 为 bef_effect_ai_check_license，value 为授权文件 LicenseBag.bundle 的路径。授权文件位于素材包内。
2. 初始化特效。对应的 key 为 bef_effect_ai_init，value 包含算法模型文件 ModelResource.bundle 的路径和设备名。算法模型文件位于素材包内。

Objective-C

- (IBAction)initExtension:(id)sender {
  NSError *error;
  NSData *data = [NSJSONSerialization
      dataWithJSONObject:@{@"licensePath": [self.resourceHelper licensePath]}
                 options:NSJSONWritingPrettyPrinted
                   error:&error];
  // 检查授权
  [self.agoraKit
      setExtensionPropertyWithVendor:@"ByteDance"
                           extension:@"Effect"
                                 key:@"bef_effect_ai_check_license"
                               value:[[NSString alloc]
                                         initWithData:data
                                             encoding:NSUTF8StringEncoding]];

  data = [NSJSONSerialization dataWithJSONObject:@{
    @"strModelDir": [self.resourceHelper modelDirPath],
    @"deviceName": @""
  }
                                         options:NSJSONWritingPrettyPrinted
                                           error:&error];
  // 初始化特效
  [self.agoraKit
      setExtensionPropertyWithVendor:@"ByteDance"
                           extension:@"Effect"
                                 key:@"bef_effect_ai_init"
                               value:[[NSString alloc]
                                         initWithData:data
                                             encoding:NSUTF8StringEncoding]];

  data =
      [NSJSONSerialization dataWithJSONObject:@{@"mode": @1, @"orderType": @0}
                                      options:NSJSONWritingPrettyPrinted
                                        error:&error];
}

4. 设置美颜效果

设置美颜效果需要调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value，目前支持以下功能：

• 设置手机角度
• 设置叠加特效（美颜、美形、美妆）
• 设置特效强度（美颜、美形、美妆）
• 设置贴纸
• 设置滤镜
• 设置滤镜强度

你可以根据场景需要进行组合调用。

参考信息

素材包结构

素材包中提供的文件详见素材包结构说明。

API 参考

• 声网 SDK 的插件相关方法和回调
• 插件的 key-value 说明