# 使用说明 (/zh-CN/realtime-media/marketplace/build/integrate-extensions/faceunity-ar/flutter) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何在你的项目中集成和使用相芯美颜道具高级版插件。 ## 技术原理 [#技术原理-2] 相芯美颜道具高级版插件是对相芯 Nama SDK 核心 API 的封装。通过[声网 SDK v4.x](/zh-CN/realtime-media/rtc) 提供的 [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#api_irtcengine_setextensionproperty) 方法,传入指定的 `key` 和 `value` 参数,你可以快速集成相芯的美颜能力。 `setExtensionProperty` 方法的 `key` 参数与相芯的 API 名称完全对应,`value` 参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用该方法时只要传入指定的 `key` 和 `value`,就可以调用对应的相芯 API,实现美颜的有关功能。 ## 前提条件 [#前提条件-2] ### 开发环境要求 [#开发环境要求] 如果你的目标平台为 iOS,你的开发环境需要满足以下需求: - Flutter 2.0 或更高版本 - Dart 2.14.0 或更高版本 - macOS 操作系统 - 最新版本的 Xcode 如果你的目标平台为 Android,你的开发环境需要满足以下需求: - Flutter 2.0 或更高版本 - Dart 2.14.0 或更高版本 - macOS 或 Windows 操作系统 - 最新版本的 Android Studio ### 运行环境要求 [#运行环境要求] - 如果你的目标平台为 iOS,你需要有一台 iOS 的设备。 - 如果你的目标平台为 Android,你需要有一台 Android 设备或模拟器。 :::info[信息] 你需要运行 `flutter doctor` 命令检查开发环境和运行环境是否满足要求。 ::: ## 示例项目 [#示例项目-2] 声网[云市场](https://console.shengwang.cn/marketplace/list/all)提供了相芯美颜道具高级版插件 Android、iOS 和 Flutter 的示例项目,你可以前往插件详情页克隆或下载并进行体验。 ## 集成和调用流程 [#集成和调用流程-2] ### 1. 集成 SDK 和插件 [#1-集成-sdk-和插件-2] 开始前,你需要在项目中分别集成声网视频 SDK 和相芯美颜道具高级版插件。 #### 1.1 使用声网 SDK 实现音视频互动 [#11-使用声网-sdk-实现音视频互动-2] 插件需要与 [RTC SDK](/zh-CN/realtime-media/rtc) 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动: #### 1.2 购买和激活插件 [#12-购买和激活插件-2] 你需要进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面,按照提示购买相芯美颜道具高级版插件,并且联系声网提供你的包名(例如 `yourCompany.yourProject.faceunity`)。随后你会收到与包名唯一对应的证书文件,用于后续集成插件。 #### 1.3 集成插件 [#13-集成插件-2] 参考以下步骤集成插件: 1. 在 Flutter 项目中,根据实际需要集成原生的 Android 和/或 iOS 插件: 1. 进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面,下载**相芯美颜道具高级版**的 Android 插件动态库压缩包。 2. 解压文件夹,将所有 `.aar` 文件保存到项目文件夹,比如 `android/libs` 路径。 3. 打开 `android/app/build.gradle` 文件,在 `dependencies` 中添加如下行: ```java implementation fileTree(dir: "${rootProject.projectDir}/libs", include: ["*.aar"]) ``` 1. 进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面,下载**相芯美颜道具高级版**的 iOS 插件动态库压缩包。 2. 解压文件夹,将所有 `.framework` 文件导入项目。 ![iOS 插件 .framework 文件导入示例](https://web-cdn.agora.io/docs-files/1676977533150) 3. 在 `.podspec` 文件中添加依赖,示例如下: ```ruby Pod::Spec.new do |s| s.name = 'Extensions' s.version = '0.1.0' s.summary = 'ByteDance effect plugin for声网 RTE extensions.' s.description = 'project.description' s.homepage = 'https://github.com/AgoraIO-Community/AgoraMarketPlace' s.author = { 'Agora' => 'developer@agora.io' } s.source = { :path => '.' } s.vendored_frameworks = 'FURenderKit.framework', 'AgoraFaceUnityExtension.framework' s.platform = :ios, '9.0' end ``` 4. 在 `Podfile` 文件中添加如下行: ```ruby pod 'Extensions', :path => "./" ``` 2. 添加证书文件:将插件包里的证书文件(`authpack.java` 或 `authpack.h`)转换成 dart 语法,并保存到项目文件夹,比如 `lib` 路径。`authpack.java` 和 `authpack.h` 所包含的证书数据一样。以转换 `authpack.h` 文件为例,将文件内的数据复制到 `List gAuthPackage = [];` 这一行的 `[]` 中即可: ```dart /// 填写示例:List gAuthPackage = [10, 13, -98, -100, 126, ...]; List gAuthPackage = [Paste your authpack data]; ``` 3. [点击下载](https://download.agora.io/marketplace/release/Agora_Marketplace_FaceUnity_v8.11.0_Resource.zip)相芯美颜插件的资源包,将所需的模型和道具 `.bundle` 文件通过 [Flutter assets](https://docs.flutter.dev/development/ui/assets-and-images) 的方式保存到项目文件夹,比如 `Resource` 路径。资源包中提供的文件详见[参考信息](#ref)。 4. 在 `pubspec.yaml` 文件中添加依赖项,示例如下: ```yaml environment: sdk: '>=2.18.6 <3.0.0' dependencies: flutter: sdk: flutter cupertino_icons: ^1.0.2 #声网 Flutter SDK 依赖项,请使用最新版本的 agora_rtc_engine agora_rtc_engine: ^6.0.0 path_provider: ^2.0.11 permission_handler: ^8.3.0 path: ^1.8.0 # The following section is specific to Flutter packages. flutter: # 添加相芯资源文件依赖项 assets: - Resource/graphics/aitype.bundle - Resource/items/ItemSticker/CatSparks.bundle - Resource/model/ai_face_processor.bundle ``` 5. 导入需要用到的 dart 文件: ```dart import 'package:agora_rtc_engine/agora_rtc_engine.dart'; import 'authpack.dart' as authpack; ``` #### 1.4 升级插件 [#14-升级插件-2] 声网云市场推荐你在更新插件版本前使用数据库工具(如 SQLite)实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。 以下是用 SQLite 来进行插件版本管理的示例: 1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。 2. 每次项目初始化时,自动检测当前项目使用的资源包版本: - 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。 - 如果记录的资源包版本与当前匹配,则正常实现业务。 如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。 以下升级流程以**相芯美颜特效**插件为例: 1. 参考[集成插件](#13-集成插件-2)章节下载所需平台最新版本的插件包和资源包。 2. 删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。 3. 删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。 :::warning[注意] 编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。 ::: ### 2. 启用插件 [#2-启用插件-2] 创建并初始化 `RtcEngine` 后,首先调用 `enableExtension` 启用插件,再调用其它 API(`enableVideo`、`joinChannel` 等)。 ```dart // On Android, you should load libAgoraFaceUnityExtension.so explicitly if (Platform.isAndroid) { await _rtcEngine.loadExtensionProvider(path: 'AgoraFaceUnityExtension'); } await _rtcEngine.enableExtension( provider: "FaceUnity", extension: "Effect", enable: true); ``` ### 3. 初始化插件 [#3-初始化插件-2] 当收到声网 SDK 的 `onExtensionStarted` 回调后,你可以在主线程或其他工作线程中调用 `setExtensionProperty` 并传入对应的 `key` 和 `value` 进行初始化: 1. 初始化。对应的 `key` 为 `fuSetup`,`value` 为证书文件 authpack 的指针。 2. 加载 AI 模型。对应的 `key` 为 `fuLoadAIModelFromPackage`,`value` 包含 AI 能力模型文件 `ai_xxx.bundle` 的路径以及 AI 能力类型。 :::note[注意] 声网建议你在 `onExtensionStarted` 回调中仅做标记处理(比如设置一个 flag),避免在回调中直接执行初始化等耗时操作,以防阻塞 SDK 事件循环。 ::: ```dart Future _initFUExtension() async { // 初始化 await _rtcEngine.setExtensionProperty( provider: 'FaceUnity', extension: 'Effect', key: 'fuSetup', value: jsonEncode({'authdata': authpack.gAuthPackage})); // 加载 AI 模型 final aiFaceProcessorPath = await _copyAsset('Resource/model/ai_face_processor.bundle'); await _rtcEngine.setExtensionProperty( provider: 'FaceUnity', extension: 'Effect', key: 'fuLoadAIModelFromPackage', // 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8 value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8})); } ``` ### 4. 设置美颜效果和人体识别 [#4-设置美颜效果和人体识别-2] 设置美颜效果需要调用 `setExtensionProperty` 并传入对应的 `key` 和 `value`,实现以下功能: - 加载道具、调节美颜强度 - 人脸、手势和人体识别 你可以根据场景需要进行组合调用。相关的 `key` 和 `value` 详见 [key-value 说明](/zh-CN/realtime-media/marketplace/reference/faceunity-ar-api)。 设置猫耳效果的示例如下: ```dart Future _setupCatSparksEffect() async { final aiFaceProcessorPath = await _copyAsset('Resource/model/ai_face_processor.bundle'); await _rtcEngine.setExtensionProperty( provider: 'FaceUnity', extension: 'Effect', key: 'fuLoadAIModelFromPackage', // 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8 value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8})); final catSparksPath = await _copyAsset('Resource/items/ItemSticker/CatSparks.bundle'); await _rtcEngine.setExtensionProperty( provider: 'FaceUnity', extension: 'Effect', key: 'fuCreateItemFromPackage', value: jsonEncode({'data': catSparksPath})); } ``` ### 5. 释放资源 [#5-释放资源-2] 需要停止使用插件时,按照以下步骤释放资源: 1. 调用 `setExtensionProperty` 并传入 `key` 为 `fuDestroyLibData`,释放插件占用的资源。 2. 收到 `fuDestroyLibData` 回调后,调用 `destroy` 方法销毁 `RtcEngine` 对象。 ## 参考信息 [#参考信息-2] ### API 参考 [#api-参考-2] - [声网 SDK 的插件相关方法和回调](/zh-CN/api-reference/rtc/flutter/extension#toc_extension) - [插件的 key-value 说明](/zh-CN/realtime-media/marketplace/reference/faceunity-ar-api) ### 常见问题 [#常见问题-2] **问题 1:运行示例项目,美颜为什么没有生效?** 通常有以下几个原因: - 插件动态库没有保存在正确位置,或者没有导入; - 相芯资源包中的文件没有保存在正确位置,或者缺少部分文件; - 证书文件与 App 包名不一致,导致鉴权失败。 **问题 2:为什么开启采集后需要 1s 左右才能渲染出视频?** 加载相芯美颜资源的操作会造成 GL 渲染线程卡顿,加载资源的过程大概耗时 800ms。建议通过业务处理(比如添加 loading 界面)规避。 **问题 3:为什么在编译 App 时会出现 `models: no match` 的报错?** 该错误通常是由于资源包匹配问题引起的。很可能是因为在编译新插件时,没有删除旧版本的 App。建议你删除旧版 App 后重新编译运行。 ### 素材包结构 [#素材包结构-2] 相芯美颜道具高级版插件的资源包文件结构详见: - [Android 资源包结构](https://gitee.com/hangzhou_xiangxin_1/FULiveDemoDroid/blob/master/doc/Android_Nama_Demo_%E8%BF%90%E8%A1%8C%E6%96%87%E6%A1%A3.md#2-demo%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84) - [iOS 资源包结构](https://gitee.com/hangzhou_xiangxin_1/FULiveDemo/blob/master/docs/iOS_Nama_SDK_%E9%9B%86%E6%88%90%E6%8C%87%E5%AF%BC%E6%96%87%E6%A1%A3.md#2-sdk%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84%E4%BD%BF%E7%94%A8%E6%96%B0%E6%9E%B6%E6%9E%84furenderkit%E5%8A%A8%E6%80%81%E5%BA%93) 更多的接口调用方式可以参考相芯 Nama SDK 的文档: - [Android 文档](https://gitee.com/hangzhou_xiangxin_1/FULiveDemoDroid/blob/master/doc) - [iOS 文档](https://gitee.com/hangzhou_xiangxin_1/FULiveDemo/tree/master/docs)