腾讯特效 SDK uniapp_uts 插件集成

跑通 Demo
1. 下载 demo ，在 App/debug/config.ts 文件中添加您的 licenseUrl 和 licenseKey ，在 App/debug/GenerateTestUserSig.js 文件中添加您 TRTC 的 SDKAppID 和 SDKSECRETKEY。
2. 找到 HBuilderX 菜单 > 发行 > App-Android/iOS-云打包。
﻿
制作 iOS 自定义基座
制作 Android 自定义基座
1. 勾选并填写下面红色框的内容，直接打包：
﻿
2. 将打包得到的 iOS_debug.ipa 文件拷贝到 App/unpackage/debug。
﻿
1. 勾选并填写下面红色框的内容，直接打包：
﻿
2. 将打包得到的 android_debug.apk 文件拷贝到 App/unpackage/debug。
﻿
使用自定义基座运行
iOS：在 HBuilderX 菜单 → 运行 → 运行到手机或模拟器 → 运行到 iOS App 基座 → 选择使用自定义基座运行→本地基座。
﻿
Android:  在 HBuilderX 菜单 → 运行 → 运行到手机或模拟器 → 运行到 Android App 基座 → 选择使用自定义基座运行→本地基座。
﻿
单击运行，成功之后，可填入任意 userID。
﻿
SDK 集成
1. 下载 uniapp_uts 插件 SDK。
2. 将 tencent-effect-xmagic 复制到您项目 App/uni_modules/ 下。
3. 根据购买的套餐包进行以下操作：
iOS：将美颜素材拷贝到 App/uni_modules/tencent-effect-xmagic/utssdk/app-ios/Resources。
Android: 将美颜素材拷贝到 App/uni_modules/tencent-effect-xmagic/utssdk/app-android/assets。
4. 编辑 app-android 或 app-ios 目录下的 config.json 文件，修改套餐包类型和美颜版本号。
﻿
﻿
﻿
﻿
﻿
﻿
SDK 使用
1. SDK 目录结构
tencent-effect-xmagic/
├── package.json                                         # 插件清单
├── README.md                                            # 本文档
└── utssdk/
    ├── interface.uts                                    # 公共接口/类型/常量定义
    ├── app-android/
    │   ├── config.json                                  # Android Maven 依赖配置
    │   ├── hybrid.kt                                    # Kotlin 原生桥接层
    │   ├── index.uts                                    # Android UTS 实现
    │   ├── assets/                                      # Android 内置资源
    │   └── libs/
    │       └── tencenteffect_uniapp_plugins_4.2.0.6.aar # 原生桥接 AAR
    └── app-ios/
        ├── config.json                                  # iOS CocoaPods 依赖配置
        ├── hybrid.swift                                 # Swift 原生桥接层
        ├── index.uts                                    # iOS UTS 实现
        ├── Frameworks/
        │   ├── TencentEffectUniPlugin.framework         # OC Framework
        │   └── TXCustomBeautyProcesserPlugin.framework  # 自定义美颜处理插件
        └── Resources/                                   # iOS 内置资源
2. 初始化流程
在应用启动后，尽可能早地完成 SDK 的初始化。例如：在 App 首页的 onLoad 方法中处理。
检查是否已复制资源，若未复制，则先复制资源鉴权 → 完成 ；若已复制，则直接鉴权 → 完成。
参考示例代码，App/pages/index/index.nvue：
import { setLicense, copyXmaigcRes } from "@/uni_modules/tencent-effect-xmagic";
﻿
function initXMagicResource() {
  uni.showLoading({ title: '正在初始化美颜...', mask: true });
﻿
  // Step 1: 检查资源是否已复制（每个版本只需一次）
  const xmagicResCopied = uni.getStorageSync('xmagic_res_copied');
  if (xmagicResCopied === true || xmagicResCopied === 'true') {
    console.log('美颜资源已复制，跳过');
    doAuth();
    return;
  }
﻿
  // Step 2: 复制美颜资源到本地
  copyXmaigcRes((result) => {
    if (result) {
      console.log('美颜资源复制成功');
      uni.setStorageSync('xmagic_res_copied', true);
      doAuth();
    } else {
      uni.hideLoading();
      uni.showToast({ title: '美颜资源复制失败', icon: 'none' });
    }
  });
﻿
  function doAuth() {
    // Step 3: 鉴权（url 和 key 从腾讯云控制台获取）
    setLicense('your-license-url', 'your-license-key', (code, msg) => {
      uni.hideLoading();
      if (code === 0) {
        console.log('美颜鉴权成功');
      } else {
        console.error(`美颜鉴权失败: code=${code}, msg=${msg}`);
        uni.showToast({ title: '美颜鉴权失败: ' + msg, icon: 'none' });
      }
    });
  }
}
﻿
onLoad(() => {
    const systemInfo = uni.getSystemInfoSync();
    statusBarHeight.value = systemInfo.statusBarHeight || 0;
    initXMagicResource();
});
注意：复制资源只做一次：通过 uni.setStorageSync('xmagic_res_copied', true) 缓存状态，后续启动跳过复制。
3. 开启或关闭美颜
 美颜功能的开启需要在相机开启之后，关闭美颜需要在关闭相机之前。
打开摄像头 → enableCustomVideoProcess(true)   [开启美颜]  
 ... 通话/预览中 ...
enableCustomVideoProcess(false) → 关闭摄像头    [关闭美颜]
示例代码：
import { enableCustomVideoProcess } from '@/uni_modules/tencent-effect-xmagic';
﻿
const handleCamera = () => {
  if (cameraStatus.value === DeviceStatus.ON) {
    // 关闭摄像头前，先关闭美颜
    enableCustomVideoProcess(false)
    closeLocalCamera()
  } else {
    // 打开摄像头后，开启美颜
    openLocalCamera({ isFront: isFrontCamera.value })
    enableCustomVideoProcess(true)
  }
};
说明：
顺序很重要：必须先关美颜再关摄像头，否则 XMagic 可能还在处理已释放的视频帧。
4. 设置美颜参数
开启美颜之后，就可以通过 setEffect 方法设置美颜参数，每个属性的参数值不一样，需要参考美颜 参数表。
// 设置美颜效果
setEffect({
  effectName: 'beauty.lutFoundationAlpha',  // 效果名称
  effectValue: 60,                           // 效果值 (0-100)
  resourcePath: undefined,                   // 资源路径（滤镜/贴纸需要）
  extraInfo: undefined,                      // 额外参数
});
API 参考
具体 API 使用可参考 uniapp_uts-API。
uniapp_uts 插件集成

本页目录：

跑通 Demo

使用自定义基座运行

SDK 集成

SDK 使用

1. SDK 目录结构

2. 初始化流程

3. 开启或关闭美颜

4. 设置美颜参数

API 参考
