# 使用说明 (/zh-CN/realtime-media/marketplace/build/integrate-extensions/sensetime-ar)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" />
## 技术原理 [#技术原理]

本文介绍如何在你的项目中集成和使用商汤高级美颜/特效系列插件。商汤高级美颜/特效系列插件是对商汤 SenseAR Effects 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，实现美颜的有关功能。

## 前提条件 [#前提条件]

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

- Android Studio 4.1 以上版本。
- 运行 Android 5.0 或以上版本的真机（非模拟器）。

## 示例项目 [#示例项目]

声网[云市场](https://console.shengwang.cn/marketplace/list/all)提供了商汤高级美颜/特效插件 Android、iOS 的示例代码，你可以前往插件详情下载并进行体验。

## 集成和调用流程 [#集成和调用流程]

### 1. 集成 SDK 和插件 [#1-集成-sdk-和插件]

开始前，你需要在项目中分别集成声网视频 SDK 和商汤高级美颜/特效系列插件。

#### 1.1 使用声网 SDK 实现音视频互动 [#11-使用声网-sdk-实现音视频互动]

插件需要与 [RTC SDK](/zh-CN/realtime-media/rtc) 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动：

<Cards>
  <Card title="实现音视频互动" href="/zh-CN/realtime-media/rtc/get-started/quick-start" />
</Cards>

#### 1.2 购买和激活插件 [#12-购买和激活插件]

你需要进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面，按照提示购买商汤高级美颜/特效系列插件。随后你会收到专属的证书 (License) 文件，用于后续集成插件。

<a id="integration"></a>
#### 1.3 集成插件 [#13-集成插件]

参考以下步骤集成插件：

1. 进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面下载**商汤高级美颜/特效系列**的 Android 插件（`.aar` ），保存到项目文件夹的 `/app/libs` 路径。
2. [点击下载](https://download.agora.io/marketplace/release/SenseTime_v8.9.3_Resources.zip)商汤美颜插件的资源包，将 License 文件以及所需的模型文件和 bundle 文件保存到项目文件夹的 `/app/src/main/assets` 路径。
3. 打开 `app/build.gradle` 文件，在 `dependencies` 中添加如下行：

   ```java
   implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
   ```

4. 导入需要用到的类：

    ```java
    import com.sensetime.stmobile.STMobileEffectNative;
    import com.sensetime.stmobile.STMobileHumanActionNative;

    import io.agora.rtc2.Constants;
    import io.agora.rtc2.IMediaExtensionObserver;
    import io.agora.rtc2.IRtcEngineEventHandler;
    import io.agora.rtc2.RtcEngine;
    import io.agora.rtc2.RtcEngineConfig;
    import io.agora.rtc2.video.VideoCanvas;
    import io.agora.rte.extension.sensetime.ExtensionManager;
    ```

#### 1.4 升级插件 [#14-升级插件]

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

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

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

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

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

  1. 参考[集成插件](#13-集成插件)章节下载所需平台最新版本的插件包和资源包。

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

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

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

### 2. 启用插件 [#2-启用插件]

初始化 `RtcEngine` 时，调用 `enableExtension` 启用插件。

```java
RtcEngineConfig config = new RtcEngineConfig();
// 监听插件事件，用于接收 onEvent 回调
config.mExtensionObserver = this;
config.addExtension("AgoraSenseTimeExtension");
mRtcEngine = RtcEngine.create(config);
// 开启插件
mRtcEngine.enableExtension("SenseTime", "Effect", enabled);
```

### 3. 初始化插件 [#3-初始化插件]

初始化插件需要调用 `setExtensionProperty` 并传入对应的 `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` 为空，传入 `{}` 即可。

```java
private void initExtension() {
    // 获取 License 路径
    File licensePath = new File(getExternalFilesDir(null), "license/" + io.agora.rte.extension.sensetime.example.Constants.mLicenseName);

    // 检查激活码
    try {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("license_path", licensePath.getPath());
        setExtensionProperty("st_mobile_check_activecode", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }

    // 创建人体行为检测句柄
    try {
        File modelsPath = new File(getExternalFilesDir(null), "models/M_SenseME_Face_Extra_Advanced_6.0.13.model");
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("model_path", modelsPath.getPath());
        jsonObject.put("config", STMobileHumanActionNative.ST_MOBILE_HUMAN_ACTION_DEFAULT_CONFIG_IMAGE);
        setExtensionProperty("st_mobile_human_action_create", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }

    // 创建特效句柄
    setExtensionProperty("st_mobile_effect_create_handle", "{}");
}

// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
    mRtcEngine.setExtensionProperty("SenseTime", "Effect", key, property);
}
```

### 4. 设置美颜效果 [#4-设置美颜效果]

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

- 设置美颜的强度：对应的 `key` 为 `st_mobile_effect_set_beauty_strength`，`value` 包含美颜类型和美颜强度。
- 加载美颜素材：对应的 `key` 为 `st_mobile_effect_set_beauty`，`value` 包含美颜类型和素材文件路径。

```java
// 设置美颜的强度
try {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("param", STEffectBeautyType.EFFECT_BEAUTY_PLASTIC_SHRINK_GODDESS_FACE);
    jsonObject.put("val", Double.valueOf(0.8).doubleValue());
    setExtensionProperty("st_mobile_effect_set_beauty_strength", jsonObject.toString());
} catch (JSONException e) {
    Log.e(TAG, e.toString());
}

// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
    mRtcEngine.setExtensionProperty("SenseTime", "Effect", key, property);
}
```

<a id="ref"></a>
## API 参考 [#api-参考]

- [声网 SDK 的插件相关方法和回调](/zh-CN/api-reference/rtc/android/extension#toc_extension)
- [插件的 key-value 说明](/zh-CN/realtime-media/marketplace/reference/sensetime-ar-api)

## 相关文档 [#相关文档]

本文只实现了最基础的美颜功能。更多的接口调用方式请参考商汤 SenseAR Effects SDK 的文档（位于商汤美颜插件的资源包内）。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" />
本文介绍如何在你的项目中集成和使用商汤高级美颜/特效系列插件。
## 技术原理 [#技术原理-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 并实现基础的音视频互动：

<Cards>
  <Card title="实现音视频互动" href="/zh-CN/realtime-media/rtc/get-started/quick-start" />
</Cards>

#### 1.2 购买和激活插件 [#12-购买和激活插件-1]

你需要进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面，按照提示购买商汤高级美颜/特效系列插件。随后你会收到专属的证书 (License) 文件，用于后续集成插件。

<a id="integration"></a>
#### 1.3 集成插件 [#13-集成插件-1]

参考以下步骤集成插件：

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

    ```shell
    .
    ├── <ProjectName>
    ├── <ProjectName>.xcodeproj
    └── Resource
    ```

2. 进入[声网控制台 > 云市场](https://console.shengwang.cn/marketplace/list/all)页面下载**商汤高级美颜/特效系列**的 iOS 插件 （`.framework`），保存到 `<ProjectName>` 路径下。
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 <AgoraRtcKit/AgoraRtcEngineKit.h>
    #import <AgoraSenseTimeExtension/st_mobile_human_action.h>
    #import <AgoraSenseTimeExtension/st_mobile_effect.h>
    ```

#### 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]];
```

<a id="ref"></a>
## 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 的文档（位于商汤美颜插件的资源包内）。
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>