使用文档

最近更新时间:2025-03-20 17:41:02

我的收藏
本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 SDK。只需遵循以下步骤,即可完成 SDK 的配置和使用。

初始化注册 License

在正式使用 腾讯礼物动画特效 SDK 时,需要先设置 License,设置 License 成功之后,才可以进行后续的 SDK 使用。
设置 License 方式如下:
说明:
此处的示例代码是在 application 启动的时候设置 License,但在您的项目中不建议在这里触发,因为此时可能没有网络权限或联网失败率较高(特别是首次启动应用时),请选择更合适的时机设置 License。
#import <TCMediaX/TCMediaX.h>
@interface AppDelegate ()<TCMediaXBaseDelegate>
@end
@implementation AppDelegate

// 使用时替换 LICENCE_URL 为自己的 LICENCE_URL
static NSString *LICENCE_URL = @"";
static NSString *LICENCE_KEY = @"";

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
[[TCMediaXBase getInstance] setLicenceURL:LICENCE_URL key:LICENCE_KEY];
[[TCMediaXBase getInstance] setDelegate:self];
return YES;
}

#pragma mark - TCMediaXBaseDelegate
- (void)onLicenseCheckCallback:(int)errcode withParam:(NSDictionary *)param {
// 注意:此回调不一定在调用线程
NSLog(@"onLicenseCheckCallback:%d",errcode);
if (errcode == TMXLicenseCheckOk) {
// 鉴权成功
} else {
// 鉴权失败
}
}
@end
注意:
1. License 是强线上检验逻辑,应用首次启动后调用 TCMediaXBase#setLicense 时,需确保网络可用。 在App首次启动时,可能还没有授权联网权限,则需要等授予联网权限后,再次调用 TCMediaXBase#setLicense。
2. 监听 TCMediaXBase#setLicence 加载结果:ILicenseCallback#onResult 接口,如果失败要根据实际情况做对应重试及引导,如果多次失败后,可以限频,并业务辅以产品弹窗等引导,让用户检查网络情况。
3. 对于多进程的 App, 确保每个使用特效播放器的进程启动时,都调用了 TCMediaXBase#setLicense。例如: Android 端使用独立进程播放特效的 App, 后台播放时进程被系统 kill 掉重启时,也要调用 TCMediaXBase#setLicense。
鉴权 errorcode 说明:
错误码
说明
0
成功。Success
-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
鉴权失败
其他
请联系腾讯云团队处理

日志管理

腾讯礼物动画特效 SDK 默认支持保存运行日志,如果测试过程中出现问题,可以提取日志反馈给腾讯云客服,您可以根据业务需要把此目录的日志上传到业务后台,用于定位线上用户问题。
腾讯礼物动画特效 SDK iOS 端的日志保存在沙箱 Documents/TCMedialog 文件夹,日志文件按照日期命名。详细日志导出教程 参考这里
播放日志默认是开启保存的, 如需要关闭,可通过 TCMediaXBase#setLogEnable 传入 NO 关闭。

播放器使用

初始化 TCEffectAnimView

- (TCEffectAnimView *)alphaAnimView {
if (!_alphaAnimView) {
_alphaAnimView = [[TCEffectAnimView alloc] init];
_alphaAnimView.backgroundColor = [UIColor clearColor];
_alphaAnimView.effectPlayerDelegate = self;
_alphaAnimView.loop = YES;
[_alphaAnimView setRenderMode:TCEPVPViewContentModeScaleToFill];
}
return _alphaAnimView;
}

添加 alphaAnimView 并布局

// 添加alphaAnimView
[self.view addSubview:self.alphaAnimView];

//布局
self.alphaAnimView.frame = self.view.bounds;

播放监听

可以在开始播放之前通过设置 effectPlayerDelegate 代理方法来监听动画播放状态:
self.alphaAnimView..effectPlayerDelegate = self;


#pragma mark - TCEPAnimViewDelegate
// 动画开始播放
- (void)tcePlayerStart:(ITCEffectPlayer *)player {
NSLog(@"player = %p, start..", player);
}

// 动画结束播放
- (void)tcePlayerEnd:(ITCEffectPlayer *)player {
NSLog(@"player = %p, end..", player);
}

// 动画播放失败
- (void)tcePlayerError:(ITCEffectPlayer *)player error:(NSError *)error {
NSLog(@"player = %p, error..", player);
}

// 动画播放事件
- (void)onPlayEvent:(ITCEffectPlayer *)player
event:(int)EvtID
withParam:(NSDictionary *)param {
NSLog(@"player = %p, EvtID = %@", player, @(EvtID));
}

获取视频资源并进行播放

TCEffectPlayer 支持播放 .mp4、.tcmp4 文件格式资源。
注意:
1. 只支持播放 本地视频资源, 如果您使用的网络视频资源, 先下载到本地再播放。
2. 动画资源可以通过 特效转换工具 来生成,除此之外也支持 VAP 格式动画资源播放。
[self.alphaAnimView startPlay:localPathUrl];

融合动画配置

实现融合动画,需要实现 TCEffectAnimViewDelegate 代理方法。

融合动画文字替换

替换文本,同时指定文本的对齐方式、颜色、是否粗体,使用 loadTextForPlayer 接口。
// 替换文本,同时指定文本的对齐方式、颜色、是否粗体,使用 loadTextForPlayer 接口,推荐使用此接口
- (TCEffectText *)loadTextForPlayer:(ITCEffectPlayer *)player
withTag:(NSString *)tag {
if (tag != nil && [tag isEqualToString:@"name"]) {
TCEffectText *effectText = [[TCEffectText alloc] init];
effectText.text = @"reText";
// TCEPTextAlignmentLeft = 0, ///< 表示文字左对齐
// TCEPTextAlignmentCenter = 1, ///< 表示文字居中对齐
// TCEPTextAlignmentRight = 2 ///< 表示文字右对齐
effectText.alignment = TCEPTextAlignmentLeft;
//effectText.fontStyle = @"bold";
//effectText.color = [UIColor blackColor];
return effectText;;
}
return nil;
}

融合动画图片替换

通过获取 tag 值后返回对应的 UIImage ,融合动画播放器内部不处理转换过程,需要在此方法里自行处理。
- (void)loadImageForPlayer:(ITCEffectPlayer *)player
context:(NSDictionary *)context
completion:(void(^)(UIImage *image,
NSError *error))completionBlock {
dispatch_async(dispatch_get_main_queue(), ^{
// 获取到当前需要替换的图片对应的 tag,然后根据 tag 返回图片
NSString *tag = context[TCEPContextSourceTypeImageIndex];
...
// 下载并缓存图片
if (image) {
completionBlock(image, nil);
} else {
completionBlock(nil, error);
}
}];
});
}
监听动画自定义资源被点击的事件,以 tag 来区分不同的融合动画区域。
- (void)tcePlayerTagTouchBegan:(ITCEffectPlayer *)player tag:(NSString *)tag {
NSString *content = [NSString stringWithFormat:@"点击了:%@",tag];
[self.view tuiad_alert:content];
}

播放配置

// 设置播放配置,非必需的步骤
TCEffectConfig *config = [[TCEffectConfig alloc] init];
[self.alphaAnimView setEffectPlayerConfig:config];
TCEffectConfig 中目前支持:
1. vapEngineType(CodecType type) :它有三个取值,分别是:
TCEPCodecTypeAVPlayer,礼物动画特效默认播放引擎。
TCEPCodecTypeVODPlayer ,腾讯云播放器SDK播放引擎。
注意:
1. 目前仅支持在播放器开始前调用 setEffectPlayerConfig 方法来设置播放配置,开始播放后不支持修改配置。
2. 目前支持的 2 种 vapEngineType 仅对 MP4 动画生效。
3. 如果设置 vapEngineType为 TCEPCodecTypeVODPlayer,则还需要单独引入腾讯云播放器SDK,以及申请、注册好其对应的 license。
2. freezeFrame 用于设置播放动画冻结帧,目前可选值:
FRAME_NONE : 默认取值,关闭 freezeFrame 能力,播放器正常播放暂停消失。
FRAME_FIRST: 播放完毕,重新开始播放到下一次首帧出现时暂停。
FRAME_LAST : 当第一次播放完毕之后,画面停留在最后一帧。

播放控制

开始播放

TCEffectPlayer 支持播放 .mp4、.tcmp4 文件格式资源。
注意:
1. 只支持播放本地视频资源, 如果您使用的网络视频资源, 先下载到本地再播放。
2. 动画资源可以通过 特效转换工具 来生成,除此之外也支持 VAP 格式动画资源播放。
NSString *mp4Url = @"xxx/xxx/tuiad_vapx_cool_sss.mp4"];
[self.alphaAnimView startPlay:mp4Url];

暂停播放

[self.alphaAnimView pause];

继续播放

[self.alphaAnimView resume];

停止播放

当不需要继续使用播放器时,需要停止播放,释放占用的资源。
[self.alphaAnimView stopPlay];

静音播放

[self.alphaAnimView setMute:YES];

循环播放

[self.alphaAnimView setLoop:YES];

常见问题

在播放过程中出现下面的日志信息,如何处理?

License checked failed! tceffect player license required!
请检查是否申请特效播放器 License,并进行了初始化注册。

如何提取运行日志?

提取礼物动画特效运行日志,请参见 日志管理

常见错误码

错误码
描述
-10003
创建线程失败
-10004
render 创建失败
-10005
配置解析失败
-10006
文件无法读取
-10007
动画视频编码格式是h265,在当前设备上不支持
-10008
参数非法
-10009
license 不合法
-10010
模拟器不支持
-100200
签名校验失败
-100201
解密数据失败
-100202
BundleID 或者 PackageName 不一致
-100203
资源过期
-100204
JSON 字段不正确
-100205
boxType 类型不支持
-100206
融合动画资源获取失败