准备工作
1. 开发环境
Android Studio(2022及以上版本)
Android SDK Tools:android-sdk 29 及以上
minSdkVersion:24
targetSdkVersion:34
2. 下载 SDK
3. 申请 License

初始化 SDK
1. 在工程中添加依赖
将下载的 tavmagic_x.x.x.x.aar 拷贝至 Android Application 工程的 libs 目录下。随后打开对应模块的
build.gradle,添加依赖引用:dependencies {implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])implementation "com.tencent.tav:libpag:4.4.35-harfbuzz"}
本地 AAR 不会自动引入上述外部依赖。示例版本对应 SDK 的依赖配置;工程已有兼容版本时统一使用,避免重复引入。
2. 设置 License 鉴权
TAV_MAGIC_LICENSE 为申请到的 License URL,TAV_MAGIC_KEY 为对应的 Key。鉴权是异步操作,需等 errorCode == 0,且 SDK 初始化成功后,再使用对应能力。TELicenseCheck.getInstance().setTELicense(context, TAV_MAGIC_LICENSE, TAV_MAGIC_KEY, (errorCode, msg) ->Log.v(TAG, String.format("auth check result, errorCode: %d, msg: %s", errorCode, msg)));
以上顺序适用于 SO 随完整 AAR 打入 APK 的方案。使用独立动态库目录时,先按下一节加载 SO,成功后再发起鉴权,避免鉴权先于库加载完成。
鉴权 errorCode 说明:
错误码 | 说明 |
0 | 成功。 |
-1 | 输入参数无效,例如 URL 或 KEY 为空。 |
-3 | 下载环节失败,请检查网络设置。 |
-4 | 从本地读取的 TE 授权信息为空,可能是 IO 失败引起。 |
-5 | 读取 VCUBE TEMP License 文件内容为空,可能是 IO 失败引起。 |
-6 | v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理。 |
-7 | 签名校验失败。请联系腾讯云团队处理。 |
-8 | 解密失败。请联系腾讯云团队处理。 |
-9 | TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理。 |
-10 | 从网络解析的 TE 授权信息为空。请联系腾讯云团队处理。 |
-11 | 把 TE 授权信息写到本地文件时失败,可能是 IO 失败引起。 |
-12 | 下载失败,解析本地 asset 也失败。 |
-13 | 鉴权失败,请检查 so 是否在包里,或者已正确设置 so 路径。 |
3004/3005 | 无效授权。请联系腾讯云团队处理。 |
3015 | Bundle Id / Package Name 不匹配。检查您的 App 使用的 Bundle Id / Package Name 和申请的是否一致,检查是否使用了正确的授权文件。 |
3018 | 授权文件已过期,需要向腾讯云申请续期。 |
其他 | 请联系腾讯云团队处理。 |
3. 初始化 SDK
1. 资源安装:将引擎资源安装到应用数据目录,耗时拷贝应在后台完成,再继续初始化。
mSdkAssetPath 为 light_assets 的父目录,例如 context.getFilesDir().getAbsolutePath();安装资源和调用 initSDK 必须使用同一路径,不能传入其下的 light_assets 目录。String mSdkAssetPath = context.getFilesDir().getAbsolutePath();int installResult = TAVMagicBase.installAIModelFilesFromAssets(context, mSdkAssetPath);if (installResult != 0) {Log.e("TAVMagicInit", "resource install failed: " + installResult);return;}
业务自带的
assets/resource(如滤镜、贴纸索引)可另外复制到业务资源目录;这与引擎资源安装是两件事。若按版本号缓存安装结果,只在必要资源全部安装成功后保存版本号,失败时保留重试条件。2. SDK 初始化:调用 initSDK 完成初始化。
// 使用静态库初始化(与下一行二选一)boolean loadRet = TAVMagicBase.initSDK(context, mSdkAssetPath);// 使用动态库初始化(与上一种二选一)// boolean loadRet = TAVMagicBase.initSDK(context, mSdkAssetPath, libsPath);if (!loadRet) {Log.e("TAVMagicInit", "SDK library loading failed");return;}// 设置日志级别(可选)TAVMagicBase.setLogLevel(Log.VERBOSE);// 配置缩略图缓存(可选)int maxMemory = (int) (Runtime.getRuntime().maxMemory() / 1024);int cacheSize = maxMemory / 4;TAVMagicBase.setThumbnailMemoryCacheSize(cacheSize);
动态方案的
libsPath 指向已落盘、匹配当前设备 ABI 的 SO 所在目录。应使用交付包中的完整配套库,libpag 仍通过 APK 中的依赖加载,不能删除上面的 libpag 依赖;若使用 slim AAR,还需准备被剥离的资源与 SO。说明:
编辑、剪同款、录制共用上述全局初始化,不需要分别调用
initSDK。initSDK 返回 true 只表示库加载成功,不代表资源完整或 License 鉴权成功;资源安装结果和鉴权回调需分别检查,License 也需包含所用能力的授权。