腾讯特效 SDK 使用文档（iOS）

一、初始化注册 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 说明：

二、日志管理

腾讯礼物动画特效 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 文件格式资源。

[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];}

十一、动画属性获取

如果需要在动画播放前获取到动画的宽高、时长，以及融合动画属性信息，你可以通过如下办法来实现：

TCEffectAnimInfo* animInfo = [TCEffectAnimView preloadTCAnimInfo:playPath config:config];

·playPath：即要获取信息的动画路径地址，类似于调用 TCEffectAnimView#startPlay() 方法时传入的参数。

·config：TCEffectConfig 实例，用于指定该动画的额外配置

十二、动画截图

如果需要在动画播放中进行截图，可以通过如下办法来实现：

UIImage *snapshotImage = [self.alphaAnimView snapshot];

使用该接口时有如下注意事项：

1. 如果在动画播放结束后截图，会返回 null。但是如果播放前设置了 FRAME_LAST ，即保留最后一帧，则此时当动画播放完成之后画面不会消失，而是会停留在最后一帧，此时截图可以拿到最后一帧内容。

2. 对于 MP4 来说：设置 setRenderMode = AspectFit 或 AspectFill 时，截图宽高比例跟原动画一致；setScaleType = ScaleToFill 时，截图宽高比例跟当时 TCEffectAnimView 宽高比例一致。

对于 TCMP4 来说：截图宽高比例始终跟原动画一致。

十三、播放配置

// 设置播放配置，非必需的步骤TCEffectConfig *config = [[TCEffectConfig alloc] init];[self.alphaAnimView setEffectPlayerConfig:config];

TCEffectConfig 中目前支持：

1. vapEngineType(CodecType type) ：它有两个取值，分别是：

·TCEPCodecTypeAVPlayer，礼物动画特效默认播放引擎。

·TCEPCodecTypeVODPlayer ，腾讯云播放器 SDK 播放引擎。

2. freezeFrame 用于设置播放动画冻结帧，目前可选值：

·FRAME_NONE : 默认取值，关闭 freezeFrame 能力，播放器正常播放暂停消失。

·FRAME_FIRST: 播放完毕，重新开始播放到下一次首帧出现时暂停。

·FRAME_LAST : 当第一次播放完毕之后，画面停留在最后一帧。

3. enableAudioFrameCallback：开启播放中音频回调开关，适用于某些情况下需要监听处理礼物动画音轨的场景。

4. enableProgressCallback： 开启播放中动画进度回调开关。

5. progressCallbackIntervalMs： 播放中动画进度回调间隔，单位毫秒，默认值200毫秒。

6. enableFrameRenderCallback：开启播放中动画帧进度回调开关。

十五、开始播放

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];

20、循环播放

[self.alphaAnimView setLoop:YES];

22、在播放过程中出现下面的日志信息，如何处理？

License checked failed! tceffect player license required!

请检查是否申请特效播放器 License，并进行了初始化注册。

23、如何提取运行日志？

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

24、常见错误码

更多常见问题请参见 常见问题列表。