Skip to main content

插播广告

一、集成建议#

  • 插播广告也叫in stream video ad、贴片广告。
  • 支持类型有VAST和VMAP。VAST一般作为前贴来单独使用。VMAP则是一种可包含前中后贴的插播广告类型。
  • 插播广告加载时需传入展示广告的容器和包含广告容器的视图控制器

主要步骤#

  • 创建TradPlusAdMediaVideo对象
  • 加载插播广告loadAd:viewController:mute:
  • 注册TradPlusADMediaVideoDelegate 回调,获取广告加载、播放、暂停、点击、关闭等回调。
  • 收到loaded:回调后,通过[TradPlusAdMediaVideo getReadyMediaVideoObject]方法可获取TradPlusMediaVideoAdObject缓存
  • 获取到TradPlusMediaVideoAdObject后可根据videoProtocol判断是Vast还是VMAP广告
  • Vast通过调用[TradPlusMediaVideoAdObject startWithViewController:viewController sceneId:nil]进行播放
  • VMAP则根据各回调事件对视频进行控制及广告播放

注意事项#

  • 不建议在tpMediaVideoAdOneLayerLoad : didFailWithError:回调中执行广告加载的方法,对广告平台方来说,短时间内多次请求,不容易得到填充,同时会造成多次无效请求,也可能会导致应用卡顿;如果产品逻辑需要在这里发起请求,开发者需要控制时间间隔和次数,比如分别在10S、30S、60S后发起请求。
  • TradPlusMediaVideoAdObject 对象需要在主线程释放
  • 插播广告在程序切换到后台时会暂停播放,如需切换前台继续播放广告,可通过监听 UIApplicationWillEnterForegroundNotification ,调用[TradPlusMediaVideoAdObject resume] 方法继续播放
  • 需要在释放销毁前手动调用destroy方法

二、TradPlusAdMediaVideo API说明#

1. 加载、展示广告#

  • 参数说明
参数说明
adUnitIDadUnitID为TradPlus后台创建的广告位ID,SDK将根据广告位ID拉取配置并请求广告
adContainer展示广告的容器
viewController包含广告容器的视图控制器
customView(TradPlusAdxInStreamView *)自定义的插播悬浮层视图,仅支持TPADX
mute是否静音(YES表示静音;NO表示有声播放)
sceneIdsceneId为广告场景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;进入广告场景
广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数,所以请在准确的位置调用。
@property (nonatomic,strong)id contentPlayhead;v10.0.0新增用于支持VMAP,传入对象需支持 GoogleIMA 的 IMAContentPlayhead协议
  • TradPlusMediaVideoAdObject API说明
方法说明
- (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;销毁
- (void)contentCompletev10.0.0新增 使用IMA后贴时需手动调用
@property (nonatomic,readonly)id _Nullable getCustomNetworkObj获取三方的资源对象 GoogleIMA对象为 IMAAd
@property (nonatomic,readonly)id _Nullable getAdsManagerv10.0.0新增 获取GoogleIMA的 IMAAdsManager对象
@property (nonatomic,readonly)TPMediaVideoProtocol videoProtocolv10.0.0新增 视频协议类型
@property (nonatomic,weak) id <TradPlusADMediaVideoDelegate> delegatev10.0.0新增 设置当前广告的回调(可选)

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)tpMediaVideoAdBidStart:(NSDictionary *)adInfo;bidding开始
- (void)tpMediaVideoAdBidEnd:(NSDictionary )adInfo error:(nullable NSError )error;bidding结束 error = nil 表示成功
- (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 *)adInfov9.4.0新增 返回IMA PlaybackReady事件
当前广告已充分缓冲且可播放时回调
- (void)tpMediaVideoAdRequestContentPause:(NSDictionary *)adInfo;v10.0.0新增 返回IMA RequestContentPause事件
- (void)tpMediaVideoAdRequestContentResume:(NSDictionary *)adInfo;v10.0.0新增 返回IMA RequestContentPause事件
- (void)tpMediaVideoAdBreakReady:(NSDictionary *)adInfo;v10.0.0新增 返回IMA kIMAAdEvent_AD_BREAK_READY事件

3. 其他设置#

  • 在加载广告前通过本地参数接口来配置
  • 设置是否允许SDK在应用程序内打开链接,YES在应用内打开链接;NO在Safari中打开链接(默认)
  • 设置是否隐藏广告播放时间,YES隐藏;NO显示(默认)
[TradPlus sharedInstance].settingDataParam = @{
@"GoogleIMA_MediaVideo_isAppBrowser":@(YES), //是否应用内打开链接
@"GoogleIMA_MediaVideo_hideCountDown":@(YES) //是否隐藏广告播放时间
};
  • v9.3.0及以上版本 设置自定义description_url(需要在加载前设置)
NSDictionary *parameters = @{@"description_url":@"https://www.tradplusad.com"};
self.mediaVideo.localParams = @{@"ima_url_parameters":parameters};
  • v9.6.0+ 支持自定义超时时间。单位:秒(默认值为8秒)
NSMutableDictionary *localParams = [[NSMutableDictionary alloc] init];
localParams[@"ima_load_video_timeout"] = @"6";
[TPMediaVideoManger sharedInstance].mediaVideo.localParams = localParams;
  • v10.2.0 设置 autoPlayAdBreaks开启。默认关闭
//如需开启则可如下进行设置
[TradPlus sharedInstance].settingDataParam = @{
@"GoogleIMA_MediaVideo_autoPlayAdBreaks":@(YES),
};
  • v10.2.0 设置控制中心 MPNowPlayingInfoCenter。默认关闭
//如需开启则可如下进行设置
[TradPlus sharedInstance].settingDataParam = @{
@"GoogleIMA_MediaVideo_disableNowPlayingInfo":@(NO),
};

三、Vast 广告#

  • googleIMA 和 TradPlus Exchange 都支持此Vast广告
  • 可提前加载好插播广告,在插播广告展示机会到来时,调用startWithViewController:来播放插播广告。
  • 因插播广告视频缓冲受网络稳定性或其他影响,可在调用startWithViewController:时,先隐藏广告容器adContainer,在收到tpMediaVideoAdStart:播放开始回调后,再显示广告容器进行展示。

示例代码#

参考: TradPlusAdMediaVideoViewController

#import <TradPlusAds/TradPlusAdMediaVideo.h>
@interface TradPlusAdMediaVideoViewController ()<TradPlusADMediaVideoDelegate >
@property (nonatomic,strong)TradPlusAdMediaVideo *mediaVideo;
@property (nonatomic,strong)TradPlusMediaVideoAdObject *mediaVideoObject;
@property (nonatomic,strong)UIView *adView;
@end
@implementation TradPlusAdMediaVideoViewController
- (void)viewDidLoad
{
[super viewDidLoad];
self.mediaVideo = [[TradPlusAdMediaVideo alloc] init];
//设置广告位ID
[self.mediaVideo setAdUnitID:@"在TP平台创建的广告位ID"];
//设置代理
self.mediaVideo.delegate = self;
//加载广告需要一些时间,可以在展示广告前提前加载好广告
[self.mediaVideo loadAd:self.adView viewController:self mute:NO];
}
- (void)showMediaVideoAd
{
//调用isAdReady方法检查是否有可用广告
if (self.mediaVideo.isAdReady)
{
//获取TradPlusMediaVideoAdObject缓存对象
TradPlusMediaVideoAdObject * mediaVideo = [self.mediaVideo getReadyMediaVideoObject];
if (mediaVideo != nil) {
self.mediaVideoObject = mediaVideo;
//viewController为视图控制器,可为nil
[self.mediaVideoObject startWithViewController:self sceneId:nil];
}
}
}
#pragma mark - TradPlusADMediaVideoDelegate
//插播广告加载成功
- (void)tpMediaVideoAdLoaded:(NSDictionary *)adInfo
{
}
//插播广告加载失败
- (void)tpMediaVideoAdLoadFailWithError:(NSError *)error
{
}
//插播广告播放开始
- (void)tpMediaVideoAdStart:(NSDictionary *)adInfo
{
}
//插播广告播放失败
- (void)tpMediaVideoAdError:(NSDictionary *)adInfo error:(NSError *)error
{
}
//插播广告被点击跳转
- (void)tpMediaVideoAdClicked:(NSDictionary *)adInfo
{
}
//插播广告播放结束
- (void)tpMediaVideoAdEnd:(NSDictionary *)adInfo
{
}
//插播广告暂停播放
- (void)tpMediaVideoAdPause:(NSDictionary *)adInfo
{
}
//插播广告继续播放
- (void)tpMediaVideoAdResume:(NSDictionary *)adInfo
{
}
//插播广告跳过
- (void)tpMediaVideoAdSkiped:(NSDictionary *)adInfo
{
}
//插播广告视频区域被点击
- (void)tpMediaVideoAdTapped:(NSDictionary *)adInfo
{
}

四、VMAP 广告#

  • v10.2.0开始支持googleIMA的VMAP

  • 使用VMAP必须在加载前设置 contentPlayhead(需支持GoogleIMA的IMAContentPlayhead协议)

  • 一般VMAP在展示页面进行加载。回调loaded就可以获取广告对象了

  • 关闭autoPlayAdBreaks时,开发者需要在收到AdBreakReady时手动调用 [self.mediaVideoObject start]来播放广告

  • 开发者需要在视频播放完时手动调[self.mediaVideoObject contentComplete]来启动VMAP的后贴广告

  • 开发者需要在收到tpMediaVideoAdRequestContentPausetpMediaVideoAdRequestContentResume时控制视频播放或暂停

⚠️注意#

由于VMAP和VAST的广告的loaded时机不同,使用VMAP广告时在TP后台设置广告时一定要选择 VMAP标签

示例代码#

参考: TradPlusAdMediaVMAPViewController

#import <TradPlusAds/TradPlusAdMediaVideo.h>
@interface TradPlusAdMediaVideoViewController ()<TradPlusADMediaVideoDelegate >
@property (nonatomic,strong)TradPlusAdMediaVideo *mediaVideo;
@property (nonatomic,strong)TradPlusMediaVideoAdObject *mediaVideoObject;
@property (nonatomic,strong) UIView *adView;
@property (nonatomic,strong) AVPlayer *contentPlayer;
@property (nonatomic,strong) AVPlayerItem *playerItem;
@property (nonatomic,strong)VideoPlayhead *videoPlayhead;
@end
@implementation TradPlusAdMediaVideoViewController
- (void)viewDidLoad
{
[super viewDidLoad];
self.mediaVideo = [[TradPlusAdMediaVideo alloc] init];
//设置广告位ID
[self.mediaVideo setAdUnitID:@"在TP平台创建的广告位ID"];
//设置代理
self.mediaVideo.delegate = self;
//设置contentPlayhead
self.videoPlayhead = [[VideoPlayhead alloc] init];
self.mediaVideo.contentPlayhead = self.videoPlayhead;
//加载广告需要一些时间,可以在展示广告前提前加载好广告
[self.mediaVideo loadAd:self.adView viewController:self mute:NO];
//监听播放完成
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(playFinish:) name:AVPlayerItemDidPlayToEndTimeNotification object:nil];
}
- (void)playFinish:(NSNotification *)notification
{
AVPlayerItem *notificationItem = (AVPlayerItem *)notification.object;
if (notificationItem != self.playerItem)
{
return;
}
//播放完成后调用 contentComplete 用于展示后贴
if(self.mediaVideoObject != nil)
{
[self.mediaVideoObject contentComplete];
}
}
#pragma mark - TradPlusADMediaVideoDelegate
- (void)tpMediaVideoAdLoaded:(NSDictionary *)adInfo
{
//获取广告对象
self.mediaVideoObject = [self.mediaVideo getReadyMediaVideoObject];
}
- (void)tpMediaVideoAdRequestContentPause:(NSDictionary *)adInfo
{
if(self.contentPlayer != nil)
{
//暂停视频
[self.contentPlayer pause];
}
}
- (void)tpMediaVideoAdRequestContentResume:(NSDictionary *)adInfo
{
if(self.contentPlayer != nil)
{
//播放视频
[self.contentPlayer play];
}
}
- (void)tpMediaVideoAdBreakReady:(NSDictionary *)adInfo
{
//收到AdBreakReady后调用start来展示广告
if(self.mediaVideoObject != nil)
{
[self.mediaVideoObject start];
}
}
//插播广告加载失败
- (void)tpMediaVideoAdLoadFailWithError:(NSError *)error
{
}
//插播广告播放开始
- (void)tpMediaVideoAdStart:(NSDictionary *)adInfo
{
}
//插播广告播放失败
- (void)tpMediaVideoAdError:(NSDictionary *)adInfo error:(NSError *)error
{
}
//插播广告被点击跳转
- (void)tpMediaVideoAdClicked:(NSDictionary *)adInfo
{
}
//插播广告播放结束
- (void)tpMediaVideoAdEnd:(NSDictionary *)adInfo
{
}
//插播广告暂停播放
- (void)tpMediaVideoAdPause:(NSDictionary *)adInfo
{
}
//插播广告继续播放
- (void)tpMediaVideoAdResume:(NSDictionary *)adInfo
{
}
//插播广告跳过
- (void)tpMediaVideoAdSkiped:(NSDictionary *)adInfo
{
}
//插播广告视频区域被点击
- (void)tpMediaVideoAdTapped:(NSDictionary *)adInfo
{
}