插播广告
一、集成建议#
- 插播广告也叫in stream video ad、贴片广告、pre-roll，一般出现在视频播放前。
- 插播广告调用时机是在用户打开视频开始播放前，位于应用内容视频播放器顶部的单独视频播放器中播放。
- 插播广告加载时需传入展示广告的容器和包含广告容器的视图控制器
主要步骤#
- 创建
TradPlusAdMediaVideo对象 - 加载插播广告
loadAd:viewController:mute: - 注册
TradPlusADMediaVideoDelegate回调，获取广告加载、播放、暂停、点击、关闭等回调。 - 收到loaded:回调后，通过
[TradPlusAdMediaVideo getReadyMediaVideoObject]方法可获取TradPlusMediaVideoAdObject缓存 - 播放插播广告
[TradPlusMediaVideoAdObject startWithViewController:viewController]
注意事项#
- 不建议在
tpMediaVideoAdOneLayerLoad : didFailWithError:回调中执行广告加载的方法，对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑需要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。 - 不建议在
tpMediaVideoAdLoaded回调中直接执行广告展示的方法，这可能导致用户体验不佳，SDK有广告会过期自动补充功能和自动加载功能，加载成功后会回调tpMediaVideoAdLoaded。开发者无法精准控制广告展示的时机。可配合产品逻辑在需要展示广告的地方，判断TradPlusMediaVideoAdObject是否有可用缓存，再展示广告。 TradPlusMediaVideoAdObject对象需要在主线程释放- 插播广告在程序切换到后台时会暂停播放，如需切换前台继续播放广告，可通过监听
UIApplicationWillEnterForegroundNotification，调用[TradPlusMediaVideoAdObject resume]方法继续播放 - 需要在释放销毁前手动调用
destroy方法
二、TradPlusAdMediaVideo API说明#
1. 加载、展示广告#
- 参数说明
| 参数 | 说明 |
|---|---|
| adUnitID | adUnitID为TradPlus后台创建的广告位ID，SDK将根据广告位ID拉取配置并请求广告 |
| adContainer | 展示广告的容器 |
| viewController | 包含广告容器的视图控制器 |
| customView | (TradPlusAdxInStreamView *)自定义的插播悬浮层视图,仅支持TPADX |
| mute | 是否静音(YES表示静音;NO表示有声播放) |
| sceneId | sceneId为广告场景ID是可选参数，默认为nil，开发者需和- (void)showAdWithSceneId:(nullable NSString *)sceneId;配套使用如需使用广告场景请参考： 广告场景说明 |
- 方法说明
| 方法 | 说明 |
|---|---|
| - (void)setAdUnitID:(NSString *)adUnitID; | 设置广告位ID |
| - (void)loadAd:(UIView )adContainer viewController:(UIViewController )viewController mute:(BOOL)mute; | 请求该广告位插播广告 |
| - (BOOL)isAdReady; | 检测该广告位是否有可用广告true为有可用广告flase为无可用广告 |
| - (nullable TradPlusMediaVideoAdObject *)getReadyMediaVideoObject; | 获取TradPlusMediaVideoAdObject对象 |
| - (void)entryAdScenario:(nullable NSString *)sceneId; | 进入广告场景 广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数，所以请在准确的位置调用。 |
TradPlusMediaVideoAdObjectAPI说明
| 方法 | 说明 |
|---|---|
| - (void)startWithViewController:(nullable UIViewController )viewController sceneId:(nullable NSString )sceneId; | 开始播放 |
| - (void)startWithViewController:(nullable UIViewController )viewController inStreamView:(nullable TradPlusAdxInStreamView )customView sceneId:(nullable NSString *)sceneId; | v9.8.0+新增 开始播放 customView：自定义的插播悬浮层视图，仅支持TPADX |
| - (void)pause; | 暂停播放 |
| - (void)resume; | 继续播放 |
| - (void)destory; | 销毁 |
2. 监听回调#
- 参数说明
| 参数 | 说明 |
|---|---|
| adInfo | 广告位ID、三方广告平台等信息，具体请参考回调信息说明 |
| error | 返回的是TP封装的错误信息：详见： 错误码说明 |
TradPlusADMediaVideoDelegate回调接口及说明
| 方法 | 说明 |
|---|---|
| - (void)tpMediaVideoAdLoaded:(NSDictionary *)adInfo; | 插播广告加载完成，首个广告源加载成功时回调，一次加载流程只会回调一次 |
| - (void)tpMediaVideoAdLoadFailWithError:(NSError *)error; | 插播广告加载失败，返回的是TP封装的错误信息。详见： 错误码说明 tpMediaVideoAdOneLayerLoad:didFailWithError:返回三方源的错误信息 |
| - (void)tpMediaVideoAdStart:(NSDictionary *)adInfo; | 插播广告播放开始 |
| - (void)tpMediaVideoAdError:(NSDictionary )adInfo error:(NSError )error; | 插播广告播放失败 |
| - (void)tpMediaVideoAdClicked:(NSDictionary *)adInfo; | 插播广告被点击跳转 |
| - (void)tpMediaVideoAdEnd:(NSDictionary *)adInfo; | 插播广告播放结束 |
TradPlusADMediaVideoDelegate回调接口及说明（可选）
| 方法 | 说明 |
|---|---|
| - (void)tpMediaVideoAdStartLoad:(NSDictionary *)adInfo; | v7.6.0+新增 开始加载流程 |
| - (void)tpMediaVideoAdOneLayerStartLoad:(NSDictionary *)adInfo; | 当每个广告源开始加载时会都会回调一次 |
| - (void)tpMediaVideoAdIsLoading:(NSDictionary *)adInfo; | v8.7.0+新增 调用load之后如果收到此回调，说明广告位仍处于加载状态，请等待上一轮load结果回调后再触发新的一轮广告加载。 |
| - (void)tpMediaVideoAdOneLayerLoaded:(NSDictionary *)adInfo; | 当每个广告源加载成功后会都会回调一次。 |
| - (void)tpMediaVideoAdOneLayerLoad:(NSDictionary )adInfo didFailWithError:(NSError )error; | 当每个广告源加载失败后会都会回调一次，返回三方源的错误信息 |
| - (void)tpMediaVideoAdAllLoaded:(BOOL)success; | 加载流程全部结束 |
| - (void)tpMediaVideoAdDidProgress:(NSDictionary *)adInfo mediaTime:(NSTimeInterval)mediaTime totalTime:(NSTimeInterval)totalTime; | 插播广告的播放进度 |
| - (void)tpMediaVideoAdPause:(NSDictionary *)adInfo; | 插播广告暂停播放 |
| - (void)tpMediaVideoAdResume:(NSDictionary *)adInfo; | 插播广告继续播放 |
| - (void)tpMediaVideoAdSkiped:(NSDictionary *)adInfo; | 插播广告跳过 |
| - (void)tpMediaVideoAdTapped:(NSDictionary *)adInfo; | 插播广告视频区域被点击 |
| - (void)tpMediaVideoAdEvent:(id)event adInfo:(NSDictionary *)adInfo; | v9.4.0新增 返回IMA各事件 event IMA为 IMAAdEvent 事件对象 |
| - (void)tpMediaVideoAdDidStartBuffering:(NSDictionary *)adInfo; | v9.4.0新增 返回IMA StartBuffering事件 当前广告媒体缓冲区为空且播放停止时回调 |
| - (void)tpMediaVideoAdDidBufferToMediaTime:(NSTimeInterval)mediaTime adInfo:(NSDictionary *)adInfo; | v9.4.0新增 返回IMA adDidBufferToMediaTime事件 当前广告媒体缓冲区回调 |
| - (void)tpMediaVideoAdPlaybackReady:(NSDictionary *)adInfo | v9.4.0新增 返回IMA PlaybackReady事件 当前广告已充分缓冲且可播放时回调 |
3. 其他设置#
- 在加载广告前通过本地参数接口来配置
- 设置是否允许SDK在应用程序内打开链接，YES在应用内打开链接；NO在Safari中打开链接(默认)
- 设置是否隐藏广告播放时间，YES隐藏；NO显示(默认)
- v9.3.0及以上版本 设置自定义description_url（需要在加载前设置）
- v9.6.0+ 支持自定义超时时间。单位：秒（默认值为8秒）
4. 推荐用法#
- 提前加载好插播广告，在插播广告展示机会到来时，调用
startWithViewController:来播放插播广告。 因插播广告视频缓冲受网络稳定性或其他影响，可在调用startWithViewController:时，先隐藏广告容器adContainer，在收到tpMediaVideoAdStart:播放开始回调后，再显示广告容器进行展示。
三、示例代码#
参考：TradPlusAdMediaVideoViewController