插播广告
一、集成建议
TP版本 | 说明 |
---|---|
V9.3.0.1 | 支持Vast(Google Ad Manager 插播广告)。 |
V9.9.0.1 | 优化回调机制,调用一次loadAd()才会收到一次loaded回调。 |
V10.1.0.1 | 支持Adx插播。 |
V10.3.0.1 | 支持VMAP。 |
V10.5.0.1 | 新增TPMediaVideo.setIMAEventListener(TPMediaVideoAdapter.OnIMAEventListener listener)用于监听VMAP所有的AdEvent事件 |
V12.5.0.1 | 新增API支持Vast多缓存。 |
- 广告会在位于应用内容视频播放器顶部的单独视频播放器中播放,广告样式如下图:
注意事项
- 不建议在
oneLayerLoadFailed
和onAdFailed
回调中执行广告加载的方法。对广告平台方来说,短时间内多次请求,不容易得到填充,同时会造成多次无效请求,也可能会导致应用卡顿;如果产品逻辑要在这里发起请求,开发者需要控制时间间隔和次数,比如分别在10S、30S、60S后发起请求。 - TPMediaVideo需要在主线程调用
loadAd()
和Start()
- 【V10.3.0.1 + 】开始支持Google IMA的VMAP
- 使用VMAP需要在加载广告前设置ContentProgressProvider(符合IMA的IMAContentPlayhead协议)
- 开发者在收到
onEvent
的AD_BREAK_READY
回调后,手动调用一次tpCustomMediaVideoAd.start("")
方法来播放广告
二、API介绍
TPMediaVideo
方法 | 说明 |
---|---|
TPMediaVideo(Context context, String adUnitId) | 创建插播广告对象。adUnitId是在TP平台创建的广告位ID。 |
loadAd(ViewGroup container,TPVideoAdPlayer tpVideoAdPlayer) | 请求广告。 container 传入展示广告所需容器,必传且不能为null。推荐使用RelativeLayout,方便控制视频居中播放。 TPVideoAdPlayer 适应Adx和IMA的接口类,必传。 |
loadAd(Object objectVideo) | 请求广告(支持Vast多缓存)。 V12.5.0.1 新增API。 objectVideo需要传入TPVideoPlayerListener的监听回调。 |
setCustomParams(Map<String, Object> map) | 自定义key-value。需要在loadAd前面调用。 |
isReady() | 检查是否有可用广告。返回true ,表示有可用广告。 |
getVideoAd() | 广告加载成功后,获取广告缓存TPCustomMediaVideoAd。 |
setAdListener(MediaVideoAdListener listener) | 设置广告监听回调。 |
setIMAEventListener (TPMediaVideoAdapter.OnIMAEventListener listener) | V10.5.0.1新增回调监听 。VMAP(多贴)时使用。 通过TpMediaVideo对象设置监听,callback中可以拿到插播所有的AdEvent事件。 替代废弃监听 TPCustomMediaVideoAd.setIMAEventListener() 。 |
onDestroy() | 销毁,释放TPMediaVideod相关对象。 |
TPCustomMediaVideoAd
- TPCustomMediaVideoAd为广告缓存对象
API | 说明 |
---|---|
pause() | 播放后暂停。 |
resume() | 暂停后继续播放广告。 |
start(String adSceneId) | 播放广告。 adSceneId广告场景ID,不使用可直接传null。 |
setCustomShowData(Map<String,Object> customShowData) | 自定义数据,展示广告前面调用。 |
getCustomNetworkObj() | 获取IMA广告对象AdsManager。AdsManager adsManager = (AdsManager)tpCustomMediaVideoAd.getCustomNetworkObj(); |
getAdDisplayContainer() | 获取广告显示容器(支持Vast多缓存)。 V12.5.0.1 新增API。 |
getTPAdVideoPlayer() | 获取请求广告时传入的TPAdVideoPlayer(支持Vast多缓存)。 V12.5.0.1 新增API。 |
setIMAEventListener (TPMediaVideoAdapter.OnIMAEventListener listener) | 通过广告缓存对象TPCustomMediaVideoAd设置的监听,callback中可以拿到插播所有的AdEvent事件。 |
onDestroy() | 销毁,释放IMA相关对象。 |
MediaVideoAdListener
方法 | 说明 |
---|---|
onAdLoaded(TPAdInfo tpAdInfo) | 一次loadAd后,广告加载成功。 V9.9.0.1优化回调机制,开发者主动调用一次load才会对应回调一次loaded,不调用不回调。 |
onAdFailed(TPAdError error) | 一次loadAd后,广告加载失败。 |
onAdClicked(TPAdInfo tpAdInfo) | 跳转按钮被点击。 |
onAdResume(TPAdInfo tpAdInfo) | 暂停后,广告继续播放。 |
onAdPause(TPAdInfo tpAdInfo) | 展示后,广告暂停播放。 |
onAdVideoStart(TPAdInfo tpAdInfo) | 广告开始播放。 |
onAdVideoEnd(TPAdInfo tpAdInfo) | 广告播放结束。 |
onAdVideoError(TPAdInfo tpAdInfo, TPAdError error) | 广告播放失败。 |
onAdSkiped(TPAdInfo tpAdInfo) | 可跳转的广告,用户点击跳过。 |
onAdTapped(TPAdInfo tpAdInfo) | 视频区域被点击。 |
onAdProgress(TPAdInfo tpAdInfo, float progress, double totaltime) | 播放进度。 progress当前播放进度 ,totaltime广告总时长。 |
其他API
- 自定义key-value:setCustomParams
(Map<String, Object>
map)配置 - 请求广告
loadAd(ViewGroup container,TPVideoAdPlayer tpVideoAdPlayer)
API前设置
参数key | 类型 | 说明value |
---|---|---|
ima_ui_countdown | int | 默认显示UI倒计时。 1 显示;其他 隐藏。 |
ima_setting_language | String | 自定义设置本d地语言,指定广告和播放器界面控件本地化时使用的语言。 参考语言区域代码地址。例如:"en"为设置本地语言为英语。 |
ima_load_video_timeout | int | 自定义超时时间。 V9.9.0.1+ 支持。单位:毫秒。 默认时间为 8000 毫秒。 |
platform_广告平台ID | Map<String, String> | 分平台传参。 V11.1.10.1+支持。 |
示例代码:
- 以设置自定义超时时间为例子
private int mLoadVideoTimeout = 8000;
...
Map<String, Object> mLocalExtras = new HashMap<>();
mLocalExtras.put("ima_load_video_timeout", mLoadVideoTimeout);
tpMediaVideo.setCustomParams(mLocalExtras);
tpMediaVideo.loadAd(mContainer,tpVideoAdPlayer);
- 分平台传参
Map<String, Object> mLocalExtras = new HashMap<>();
Map<String, String> paramsGAM = new HashMap<>();
Map<String, String> paramsPremiumAds = new HashMap<>();
Map<String, String> paramsBeesAds = new HashMap<>();
Map<String, String> paramsMangoX = new HashMap<>();
Map<String, Map<String, String>> networkParams = new HashMap<>();
networkParams.put("platform_48",paramsGAM);
networkParams.put("platform_64",paramsPremiumAds);
networkParams.put("platform_69",paramsBeesAds);
networkParams.put("platform_71",paramsMangoX);
mLocalExtras.put("ima_url_parameters", networkParams);
tpMediaVideo.setCustomParams(mLocalExtras);
三、Vast 广告
- 加载时需传入展示广告的容器。
- 插播广告在程序切换到后台时会暂停播放,如需切换前台继续播放广告,可在生命周期onPause()和onResume()中分别调用
tpCustomMediaVideoAd.pause()
和tpCustomMediaVideoAd.resume()
方法进行控制。 - V10.1.0.1 开始支持Adx的插播, 同时适应Adx和IMA的 TPVideoAdPlayer 接口所创建的NewVideoAdPlayerAdapter类,NewVideoAdPlayerAdapter具体实现请参考Demo
请求广告
private RelativeLayout mContainer;
private NewVideoAdPlayerAdapter newVideoAdPlayerAdpter;
private TPMediaVideo tpMediaVideo;
...
tpMediaVideo = new TPMediaVideo(context,"在TP平台创建的广告位ID");
tpMediaVideo.setAdListener(new MediaVideoAdListener());
// 推荐容器使用RelativeLayout,使广告videoview居中显示
adContainer = new RelativeLayout(context);
AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
VideoView videoView = new VideoView(MediaVideoActiviy.this);
// 适应Adx和IMA的 TPVideoAdPlayer 接口所创建的NewVideoAdPlayerAdapter类
newVideoAdPlayerAdpter = new VideoAdPlayerAdapter(videoView, audioManager, true);
// 容器和NewVideoAdPlayerAdapter为必传参数
tpMediaVideo.loadAd(mContainer,newVideoAdPlayerAdpter);
播放广告
tpMediaVideo.setAdListener(new MediaVideoAdListener() {
@Override
public void onAdLoaded(TPAdInfo tpAdInfo) {
// 收到加载成功回调后
boolean ready = tpMediaVideo.isReady();
if (ready) {
Log.i(TAG, "isReady: " + ready);
// 获取广告缓存tpCustomMediaVideoAd
tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();
// 通过广告缓存对象进行展示start()
if (tpCustomMediaVideoAd != null) {
tpCustomMediaVideoAd.start(null);
}
}
}
});
V12.5.0.1+ 新增API支持Vast多缓存
请求广告
private RelativeLayout mContainer;
private TPMediaVideo tpMediaVideo;
...
public void loadMediaVideo() {
tpMediaVideo = new TPMediaVideo(context,"在TP平台创建的广告位ID");
tpMediaVideo.setAdListener(new MediaVideoAdListener());
TPVideoPlayerListener tpVideoPlayerListener = new TPVideoPlayerListener() {
@Override
public Object getTPVideoPlayer() {
// 多个缓存需要传入多个TPVideoPlayer
return getVideoAdPlayer();
}
@Override
public Object getContentProgressProvider() {
//内容播放进度ContentProgressProvider
return null;
}
};
// 请求广告
tpMediaVideo.loadAd(tpVideoPlayerListener);
}
private VideoView videoView;
public TPVideoAdPlayer getVideoAdPlayer() {
AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
videoView = new VideoView(MediaVideoActiviy.this);
// 适应Adx和IMA的 TPVideoAdPlayer 接口所创建的VideoAdPlayerAdapter类
VideoAdPlayerAdapter videoAdPlayer = new VideoAdPlayerAdapter(videoView, audioManager, true);
}
播放广告
tpMediaVideo.setAdListener(new MediaVideoAdListener() {
@Override
public void onAdLoaded(TPAdInfo tpAdInfo) {
// 收到加载成功回调后
boolean ready = tpMediaVideo.isReady();
if (ready) {
// 获取广告缓存tpCustomMediaVideoAd
tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();
// 获取当前缓存对象使用的TPAdVideoPlayer
Object tpAdVideoPlayerObj = tpCustomMediaVideoAd.getTPAdVideoPlayer();
TPVideoAdPlayer tpAdVideoPlayer = null;
if (tpAdVideoPlayerObj instanceof TPVideoAdPlayer) {
tpAdVideoPlayer = (TPVideoAdPlayer)tpAdVideoPlayerObj;
}
// 获取当前缓存对象的广告显示容器
Object adDisplayContainerObj = tpCustomMediaVideoAd.getAdDisplayContainer();
if (adDisplayContainerObj instanceof AdDisplayContainer) {
// Google IMA Vast
AdDisplayContainer adDisplayContainer = (AdDisplayContainer) adDisplayContainerObj;
if (adDisplayContainer != null) {
ViewGroup adContainer = adDisplayContainer.getAdContainer();
if (adContainer != null) {
if (videoView.getParent() != null) {
((ViewGroup) videoView.getParent()).removeView(videoView);
}
mAdContainer.addView(videoView);
mAdContainer.addView(adContainer);
// 通过广告缓存对象进行展示start()
tpCustomMediaVideoAd.start("");
}
}
}else if (adDisplayContainerObj instanceof FrameLayout) {
// TP Exchange
FrameLayout adContainer = (FrameLayout) adDisplayContainerObj;
if (adContainer != null) {
if (videoView.getParent() != null) {
((ViewGroup) videoView.getParent()).removeView(videoView);
}
mAdContainer.addView(videoView);
mAdContainer.addView(adContainer);
// 通过广告缓存对象进行展示start()
tpCustomMediaVideoAd.start("");
}
}
}
}
});
四、VMAP 广告
-
加载时需传入展示广告的容器
-
需要在请求广告前传入ContentProgressProvider
-
设置setIMAEventListener监听,开发者需监听AD_BREAK_READY回调,控制播放时机
-
ContentProgressProvider具体实现请参考Demo VideoPlayerController中的示例代码
-
创建广告位时需要选择VMAP协议类型,如图:
请求广告
private RelativeLayout mContainer;
private VideoAdPlayerAdapter newVideoAdPlayerAdpter;
private TPMediaVideo tpMediaVideo;
private ContentProgressProvider contentProgressProvider;
...
tpMediaVideo = new TPMediaVideo(context,"在TP平台创建的广告位ID");
tpMediaVideo.setAdListener(new MediaVideoAdListener());
// 推荐容器使用RelativeLayout,使广告videoview居中显示
adContainer = new RelativeLayout(context);
AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
VideoView videoView = new VideoView(MediaVideoActiviy.this);
// 适应Adx和IMA的 TPVideoAdPlayer 接口所创建的NewVideoAdPlayerAdapter类
newVideoAdPlayerAdpter = new VideoAdPlayerAdapter(videoView, audioManager, true);
// SDK 检查内容进度的 ContentProgressProvider 接口实现
Map<String, Object> mLocalExtras = new HashMap<>();
mLocalExtras.put("ima_content_provider", contentProgressProvider);
tpMediaVideo.setCustomParams(mLocalExtras);
// 容器和NewVideoAdPlayerAdapter为必传参数
tpMediaVideo.loadAd(mContainer,newVideoAdPlayerAdpter);
播放广告
- V10.5.0.1新增回调监听,VMAP(多贴)时使用
// 通过TpMediaVideo对象设置监听,callback中可以拿到插播所有的AdEvent事件
tpMediaVideo.setIMAEventListener(new TPMediaVideoAdapter.OnIMAEventListener() {
@Override
public void onEvent(Object o) {
AdEvent adEvent = (AdEvent)o;
switch (adEvent.getType()) {
case AD_BREAK_READY:
// VMAP广告加载成功,开发者需要自己控制调用播放时机
// 获取广告缓存tpCustomMediaVideoAd,通过广告缓存对象进行展示start()
boolean ready = tpMediaVideo.isReady();
if (ready) {
tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();
if (tpCustomMediaVideoAd != null) {
tpCustomMediaVideoAd.start(null);
}
}
...
break;
}
}
});