本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 SDK。只需遵循以下步骤,即可完成 SDK 的配置和使用。
初始化注册 License
在正式使用 腾讯礼物动画特效 SDK 时,需要先设置 License,设置 License 成功之后,才可以进行后续的 SDK 使用。
设置 License 方式如下:
说明:
此处的示例代码是在 application 启动的时候设置 License,但在您的项目中不建议在这里触发,因为此时可能没有网络权限或联网失败率较高(特别是首次启动应用时),请选择更合适的时机设置 License。
#import <TCMediaX/TCMediaX.h>@interface AppDelegate ()<TCMediaXBaseDelegate>@end@implementation AppDelegate// 使用时替换 LICENCE_URL 为自己的 LICENCE_URLstatic 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 默认支持保存运行日志,如果测试过程中出现问题,可以提取日志反馈给腾讯云客服,您可以根据业务需要把此目录的日志上传到业务后台,用于定位线上用户问题。
播放日志默认是开启保存的, 如需要关闭,可通过
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 *)playerevent:(int)EvtIDwithParam:(NSDictionary *)param {NSLog(@"player = %p, EvtID = %@", player, @(EvtID));}
获取视频资源并进行播放
TCEffectPlayer 支持播放 .mp4、.tcmp4 文件格式资源。
[self.alphaAnimView startPlay:localPathUrl];
融合动画配置
实现融合动画,需要实现 TCEffectAnimViewDelegate 代理方法。
融合动画文字替换
替换文本,同时指定文本的对齐方式、颜色、是否粗体,使用 loadTextForPlayer 接口。
// 替换文本,同时指定文本的对齐方式、颜色、是否粗体,使用 loadTextForPlayer 接口,推荐使用此接口- (TCEffectText *)loadTextForPlayer:(ITCEffectPlayer *)playerwithTag:(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 *)playercontext:(NSDictionary *)contextcompletion:(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 文件格式资源。
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 | 融合动画资源获取失败 |