本文将详细介绍如何在项目中快速地使用腾讯礼物动画特效 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];}
动画属性获取
如果需要在动画播放前获取到动画的宽高、时长,以及融合动画属性信息,您可以通过如下办法来实现:
TCEffectAnimInfo* animInfo = [TCEffectAnimView preloadTCAnimInfo:playPath config:config];
playPath:即要获取信息的动画路径地址,类似于调用 TCEffectAnimView#startPlay() 方法时传入的参数。
config:TCEffectConfig 实例,用于指定该动画的额外配置
注意:
当您播放动画时,调用过 TCEffectAnimView#setEffectPlayerConfig() 方法,设置了包含 extendMapParams 的 TCEffectConfig 实例,那么此时您在调用当前 preloadTCAnimInfo 方法时,第二个入参传入该 TCEffectConfig 实例,以确保动画正常解析,否则传入 null 即可。
对于旧版本不含 vapc box 的 vap 动画,当前方法不能解析出其中的动画配置信息,此时会返回 null。
当前方法涉及 IO 操作,需要注意线程调用。
播放配置
// 设置播放配置,非必需的步骤TCEffectConfig *config = [[TCEffectConfig alloc] init];[self.alphaAnimView setEffectPlayerConfig:config];
TCEffectConfig 中目前支持:
1. vapEngineType(CodecType type) :它有两个取值,分别是:
TCEPCodecTypeAVPlayer,礼物动画特效默认播放引擎。
TCEPCodecTypeVODPlayer ,腾讯云播放器 SDK 播放引擎。
注意:
目前仅支持在播放器开始前调用 setEffectPlayerConfig 方法来设置播放配置,开始播放后不支持修改配置。
目前支持的 2 种 vapEngineType 仅对 MP4 动画生效。
如果设置 vapEngineType为 TCEPCodecTypeVODPlayer,则还需要单独引入腾讯云播放器 SDK,以及申请、注册好其对应的 license。
2. freezeFrame 用于设置播放动画冻结帧,目前可选值:
FRAME_NONE : 默认取值,关闭 freezeFrame 能力,播放器正常播放暂停消失。
FRAME_FIRST: 播放完毕,重新开始播放到下一次首帧出现时暂停。
FRAME_LAST : 当第一次播放完毕之后,画面停留在最后一帧。
3. enableAudioFrameCallback:开启播放中音频回调开关,适用于某些情况下需要监听处理礼物动画音轨的场景。
注意:
目前仅支持在播放器开始前调用 setEffectPlayerConfig() 方法来设置播放配置,开始播放后不支持修改配置。
仅在 CodecType为 TCEPCodecTypeVODPlayer,并且动画类型是 MP4/TEP 时生效。
开启开关之后,可以通过 TCEPAnimViewDelegate#tcePlayerAudioFrame 方法来设置监听回调。
4. enableProgressCallback: 开启播放中动画进度回调开关。
5. progressCallbackIntervalMs: 播放中动画进度回调间隔,单位毫秒,默认值200毫秒。
注意:
注意该配置在 enableProgressCallback 开关打开的前提下才会生效。
开启开关之后,可以在 TCEPAnimViewDelegate#onPlayEvent 回调中监听 event:TCEPConstant.TCEP_PLAYER_EVT_PROGRESS 来获取到当前播放进度。
时间间隔建议不要设置过小,间隔过小会影响性能。
播放控制
开始播放
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 | 融合动画资源获取失败 |