使用拓幻美颜特效系列插件

本文介绍如何在你的项目中集成和使用拓幻美颜特效系列插件（以下简称“拓幻美颜插件”），包括 Android 和 iOS 平台。

技术原理

拓幻美颜插件是对拓幻 TiSDK 核心 API 的封装。通过调用声网视频 SDK v4.0.0 的 setExtensionProperty 或 setExtensionPropertyWithVendor方法，传入指定的 key 和 value 参数，你可以快速集成拓幻的美颜能力。

以 setExtensionProperty 为例，其中的 value 参数以 JSON 格式包装拓幻的 API 部分或全部参数。因此，调用 setExtensionProperty 时只要传入指定的 key 和 value，就可以调用对应的拓幻 API，实现美颜的有关功能。setExtensionPropertyWithVendor 同理。 支持的 key 和 value 详见拓幻美颜特效系列插件接口说明。

前提条件

• Android 开发环境需满足以下要求：
  • Android Studio 4.1 以上版本。
  • 运行 Android 5.0 或以上版本的真机（非模拟器）。
• iOS 开发环境需满足以下要求：
  • Xcode 10.0 或以上版本。
  • 运行 iOS 10.0 或以上版本的真机（非模拟器）。

准备工作

使用声网 SDK 实现视频通话

拓幻美颜插件需要与声网视频 SDK v4.0.0 搭配使用。参考以下文档集成视频 SDK v4.0.0 并实现基础的视频通话：

• 实现视频通话（Android）
• 实现视频通话（iOS）

购买和激活插件

在声网控制台购买和激活拓幻美颜插件，购买时需要保存好获取的证书文件，用于后续集成插件。

集成插件

Android

1. 在声网云市场下载页面下载拓幻美颜特效系列的 Android 插件包。

2. 解压后，将所有 .aar 文件保存到项目文件夹的 /app/libs 路径。

3. 联系声网获取拓幻美颜插件的资源包，将所需的模型和道具文件保存到项目文件夹的 /app/src/main/assets 路径。

4. 打开 app/build.gradle 文件，在 dependencies 中添加如下行

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

5. 导入需要用到的类：

   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;

iOS

1. 在声网云市场下载页面下载拓幻美颜特效系列的 iOS 插件包。

2. 解压文件夹，将所有 .framework 库文件保存到你的项目文件夹下。

3. 将证书文件 TiKey.h 保存到项目文件夹下。

4. 联系声网获取拓幻美颜插件的资源包，将 TiSDKResource.bundle 保存到项目文件夹下。

5. 在 Xcode 中添加动态库，确保 Embed 属性设置为 Embed & Sign。

6. 导入需要用到的头文件:

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

调用流程

本节介绍插件相关接口的调用流程。接口的参数解释详见接口说明。

步骤1. 启用插件

Android

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

private void enableExtension(boolean enabled) {
    mRtcEngine.enableExtension("Tillusory", "TiSDK", enabled);
}

iOS

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

[self.agoraKit enableExtensionWithVendor:@"Tillusory"
                               extension:@"TiSDK"
                                 enabled:self.enable];

步骤2. 初始化插件

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

Android

private void initExtension() {
    // 初始化
    try {
        //在线鉴权方式
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("key",TiSDKKey);
        setExtensionProperty("tiInit", jsonObject.toString());
        //离线鉴权方式
        //JSONObject jsonObject = new JSONObject();
        //jsonObject.put("key",TiSDKKey);
        //setExtensionProperty("tiInitOffline", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }
}

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

iOS

- (void)initExtension{
    // 在线鉴权方式
    [self.agoraKit setExtensionPropertyWithVendor:@"Tillusory"
                                        extension:@"TiSDK"
                                              key:@"tiInit"
                                            value:[self toJson:@{
                                                @"key":TiSDKKey
                                            }]];
    /*
    // 离线鉴权方式
    [self.agoraKit setExtensionPropertyWithVendor:@"Tillusory"
                                        extension:@"TiSDK"
                                              key:@"tiInitOffline"
                                            value:[self toJson:@{
                                                @"key":TiSDKKey
                                            }]];
    */
}

3. 设置美颜效果

调用 setExtensionProperty（Android）或 setExtensionPropertyWithVendor（iOS）并传入对应的 key 和 value，实现以下功能：

1. 全局美颜、一键美颜
2. 精准美肤、美型、脸型
3. 萌颜、滤镜、美妆美发

你可以根据场景需要进行组合调用。对应的 key 和 value 详见接口说明。

示例项目

在 Gitee 上查看完整的示例代码和项目结构

运行步骤

Android

1. 克隆仓库：

git clone https://gitee.com/tillusory/agora-tillusory-extension-demo.git

2. 从声网云市场下载页面下载拓幻美颜插件的 Android 插件包。解压后，将所有 .aar 文件保存到 agora-tillusory-extension-demo/Android/app/libs 路径 。(libs文件夹需自行创建）
3. 联系声网获取证书文件和资源包。
4. 将资源包中所需的模型和道具文件保存到项目文件夹的 agora-tillusory-extension-demo/Android/app/src/main/assets路径 。(assets文件夹需自行创建）
5. 在 Android Studio 中打开示例项目 agora-tillusory-extension-demo/Android。
6. 将项目与 Gradle 文件同步。
7. 打开 agora-tillusory-extension-demo/Android/app/src/main/java/io/agora/rte/extension/tiui/example/Constants.java，进行如下修改：
   • 将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开始使用 Agora 平台。
   • mToken 和 mLicenseName 在运行demo时不必填写。

public interface Constants {
    String mAppId = "<YOUR_APP_ID>";
    String mToken = null;
    String mLicenseName = "<YOUR_LICENSE_NAME>";
}

8. 打开 agora-tillusory-extension-demo/Android/app/src/main/java/io/agora/rte/extension/tiui/example /TiKey.java，进行如下修改：
   • 将 <YOUR_SDK_KEY> 替换为在声网购买的由拓幻提供的测试key

public interface TiKey {
    String TiSDKKey = "<YOUR_SDK_KEY>";
}

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

iOS

1. 克隆仓库：

  git clone https://gitee.com/tillusory/agora-tillusory-extension-demo.git

2. 从声网云市场下载页面下载拓幻美颜插件的 iOS 插件包。解压后，将所有 .framwork 库文件保存到 agora-tillusory-extension-demo/iOS/ExtensionExample 。
3. 联系声网获取证书文件和资源包。
4. 将获取的证书文件 TiKey.h 和资源包 TiSDKResource.bundle 保存到 agora-tillusory-extension-demo/iOS/ExtensionExample 路径。
5. 在终端中进入 agora-tillusory-extension-demo/iOS 目录，运行以下命令使用 CocoaPods 安装依赖：

   pod install

6. 在 Xcode 中打开项目 ExtensionExample.xcworkspace。
7. 打开 Config.h，将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开始使用 Agora 平台。

• token 在运行demo时不必填写。

  NSString *const appID = @"<YOUR_APP_ID>";
  NSString *const token = nil;

8. 打开 agora-tillusory-extension-demo/iOS/ExtensionExample/TiKey.h，进行如下修改：

• 将 <YOUR_TI_SDK_KEY> 替换为在声网购买的由拓幻提供的测试key

  NSString *const TiSDKKey = @"<YOUR_TI_SDK_KEY>";

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

预期效果

运行成功后，示例项目会安装到你的 Android 或 iOS 设备上。

1. 启动 app 后，拓幻美颜插件默认开启。你可以在界面上看到 enableExtension 、 setSticker 和 setFilter 按钮和faces:0人脸数量显示。
2. 点击 setSticker 加载贴纸效果。默认是机械猫耳特效。
3. 点击 setFilter 设置滤镜效果。默认是日系风格。

接口说明

插件相关所有接口的参数解释详见接口说明。