# 使用说明 (/zh-CN/realtime-media/marketplace/build/integrate-extensions/sensetime-ar/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何在你的项目中集成和使用商汤高级美颜/特效系列插件。 ## 技术原理 [#技术原理-1] 商汤高级美颜/特效系列插件是对商汤 SenseAR Effects SDK核心 API 的封装。通过[声网 SDK v4.x](/zh-CN/realtime-media/rtc) 提供的 [`setExtensionPropertyWithVendor`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_setextensionproperty) 方法,传入指定的 `key` 和 `value` 参数,你可以快速集成商汤的美颜能力。 `setExtensionPropertyWithVendor` 方法的 `key` 参数与商汤的 API 名称完全对应,`value` 参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用该方法时只要传入指定的 `key` 和 `value`,就可以调用对应的商汤 API,实现美颜的有关功能。 ## 前提条件 [#前提条件-1] iOS 开发环境需满足以下要求: - Xcode 9.0 或以上版本。 - 运行 iOS 9.0 或以上版本的真机(非模拟器)。 ## 示例项目 [#示例项目-1] 声网[云市场](https://console.shengwang.cn/marketplace/list/all)提供了商汤高级美颜/特效插件 Android、iOS 的示例代码,你可以前往插件详情下载并进行体验。 ## 集成和调用流程 [#集成和调用流程-1] ### 1. 集成 SDK 和插件 [#1-集成-sdk-和插件-1] 开始前,你需要在项目中分别集成声网视频 SDK 和商汤高级美颜/特效系列插件。 #### 1.1 使用声网 SDK 实现音视频互动 [#11-使用声网-sdk-实现音视频互动-1] 插件需要与 [RTC SDK](/zh-CN/realtime-media/rtc) 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动: #### 1.2 购买和激活插件 [#12-购买和激活插件-1] 你需要进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面,按照提示购买商汤高级美颜/特效系列插件。随后你会收到专属的证书 (License) 文件,用于后续集成插件。 #### 1.3 集成插件 [#13-集成插件-1] 参考以下步骤集成插件: 1. 在项目文件夹下新建 `Resource` 文件夹,位置如下: ```shell . ├── ├── .xcodeproj └── Resource ``` 2. 进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面下载**商汤高级美颜/特效系列**的 iOS 插件 (`.framework`),保存到 `` 路径下。 3. [点击下载](https://download.agora.io/marketplace/release/SenseTime_v8.9.3_Resources.zip)商汤美颜插件的资源包,将 License 文件以及所需的模型文件和 bundle 文件保存到 `Resource` 路径下。 4. 在 Xcode 中进入 **TARGETS** > **Build Settings** > **Build Options** > **Enable Bitcode**,设置为 **No**,关闭 Bitcode。 5. 导入需要用到的头文件: ```objc #import #import #import ``` #### 1.4 升级插件 [#14-升级插件-1] 声网云市场推荐你在更新插件版本前使用数据库工具(如 SQLite)实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。 以下是用 SQLite 来进行插件版本管理的示例: 1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。 2. 每次项目初始化时,自动检测当前项目使用的资源包版本: - 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。 - 如果记录的资源包版本与当前匹配,则正常实现业务。 如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。 以下升级流程以**相芯美颜特效**插件为例: 1. 参考[集成插件](#13-集成插件-1)章节下载所需平台最新版本的插件包和资源包。 2. 删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。 3. 删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。 :::warning[注意] 编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。 ::: ### 2. 启用插件 [#2-启用插件-1] 初始化 `AgoraRtcEngineKit` 时,调用 `enableExtensionWithVendor` 启用插件。 ```objc [self.agoraKit enableExtensionWithVendor:@"SenseTime" extension:@"Effect" enabled:self.enable]; ``` ### 3. 初始化插件 [#3-初始化插件-1] 初始化插件需要调用 `setExtensionPropertyWithVendor` 并传入对应的 `key` 和 `value`,具体顺序如下: 1. 检查激活码。对应的 `key` 为 `st_mobile_check_activecode`,`value` 为 License 文件的路径。 2. 创建人体行为检测句柄。对应的 `key` 为 `st_mobile_human_action_create`,`value` 包含模型文件的路径和配置选项。 3. 创建特效句柄。对应的 `key` 为 `st_mobile_effect_create_handle`,`value` 为空,传入 `{}` 即可。 ```objc - (IBAction)initExtension:(id)sender { { NSString* fileName = [[license_name lastPathComponent] stringByDeletingPathExtension]; NSString* extension = [license_name pathExtension]; NSError *error; NSData *data = [NSJSONSerialization dataWithJSONObject:@{ @"license_path": [[NSBundle mainBundle] pathForResource:fileName ofType:extension] } options:NSJSONWritingPrettyPrinted error:&error]; // 检查激活码 [self.agoraKit setExtensionPropertyWithVendor:@"SenseTime" extension:@"Effect" key:@"st_mobile_check_activecode" value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]]; } { NSString *model_path = [[[NSBundle mainBundle] pathForResource:@"model" ofType:@"bundle"] stringByAppendingFormat:@"/%@", @"M_SenseME_Face_Extra_Advanced_6.0.13.model"]; NSError *error; NSData *data = [NSJSONSerialization dataWithJSONObject:@{ @"model_path": model_path, @"config": @(ST_MOBILE_HUMAN_ACTION_DEFAULT_CONFIG_IMAGE) } options:NSJSONWritingPrettyPrinted error:&error]; // 创建人体行为检测句柄 [self.agoraKit setExtensionPropertyWithVendor:@"SenseTime" extension:@"Effect" key:@"st_mobile_human_action_create" value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]]; } { // 创建特效句柄 [self.agoraKit setExtensionPropertyWithVendor:@"SenseTime" extension:@"Effect" key:@"st_mobile_effect_create_handle" value:@"{}"]; } } ``` ### 4. 设置美颜效果 [#4-设置美颜效果-1] 设置美颜效果需要调用 `setExtensionPropertyWithVendor` 并传入对应的 `key` 和 `value`,目前支持以下功能: - 设置美颜的强度:对应的 `key` 为 `st_mobile_effect_set_beauty_strength`,`value` 包含美颜类型和美颜强度。 - 加载美颜素材:对应的 `key` 为 `st_mobile_effect_set_beauty`,`value` 包含美颜类型和素材文件路径。 ```objc NSError *error; NSData *data = [NSJSONSerialization dataWithJSONObject:@{ @"param": @(EFFECT_BEAUTY_PLASTIC_SHRINK_GODDESS_FACE), @"val": @0.8f } options:NSJSONWritingPrettyPrinted error:&error]; [self.agoraKit setExtensionPropertyWithVendor:@"SenseTime" extension:@"Effect" key:@"st_mobile_effect_set_beauty_strength" value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]]; ``` ## API 参考 [#api-参考-1] - [声网 SDK 的插件相关方法和回调](/zh-CN/api-reference/rtc/ios/extension#toc_extension) - [插件的 key-value 说明](/zh-CN/realtime-media/marketplace/reference/sensetime-ar-api) ## 相关文档 [#相关文档-1] 本文只实现了最基础的美颜功能。更多的接口调用方式请参考商汤 SenseAR Effects SDK 的文档(位于商汤美颜插件的资源包内)。