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

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

技术原理

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

以 setExtensionProperty 为例，其中的 key 参数与拓幻的 API 名称完全对应，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.x 搭配使用。参考以下文档集成视频 SDK v4.x 并实现基础的视频通话：

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

购买和激活插件

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

集成插件

Android

1. 进入声网控制台 > 云市场页面下载拓幻美颜插件的 Android 插件包。解压后，将所有 .aar 文件保存到项目文件夹的 /app/libs 路径。

2. 点击下载拓幻美颜插件的资源包，将所需的模型和道具文件保存到项目文件夹的 /app/src/main/assets 路径。

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

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

4. 导入需要用到的类：

   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	Java	agora-tillusory-extension-demo/Android
iOS	Objective-C	agora-tillusory-extension-demo/iOS

运行步骤

Android

1. 克隆仓库：

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

2. 从声网云市场下载页面下载拓幻美颜插件的 Android 插件包。解压后，将所有 .aar 文件保存到 agora-tillusory-extension-demo/Android/app/libs 路径 。

3. 点击下载拓幻美颜插件的资源包，将资源包中所需的模型和道具文件保存到项目文件夹的 agora-tillusory-extension-demo/Android/app/src/main/assets 路径。

4. 在 Android Studio 中打开示例项目 agora-tillusory-extension-demo/Android。

5. 将项目与 Gradle 文件同步。

6. 打开 agora-tillusory-extension-demo/Android/app/src/main/java/io/agora/rte/extension/tiui/example/Constants.java，进行如下修改：

   • 将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开始使用声网平台。
   • 将 <YOUR_APP_KEY> 和 <YOUR_APP_SECRET> 分别替换为你的 appKey 和 appSecret。获取方式详见购买和激活插件。

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

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

iOS

1. 克隆仓库：

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

2. 从声网云市场下载页面下载拓幻美颜插件的 iOS 插件包。解压后，将所有 .framework 库文件保存到 agora-tillusory-extension-demo/iOS/ExtensionExample 。

3. 将获取的证书文件 TiKey.h 和资源包（点击下载） 中的 TiSDKResource.bundle 保存到 agora-tillusory-extension-demo/iOS/ExtensionExample 路径。

4. 在终端中进入 agora-tillusory-extension-demo/iOS 目录，运行以下命令使用 CocoaPods 安装依赖：

    pod install

5. 在 Xcode 中打开项目 ExtensionExample.xcworkspace。

6. 打开 Config.h，将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开始使用声网平台。

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

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

预期效果

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

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

接口说明

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