跳到主要内容

插播广告

MediaVideo Demo地址

一、集成建议​

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_countdownint默认显示UI倒计时。
1 显示；其他 隐藏。
ima_setting_languageString自定义设置本d地语言，指定广告和播放器界面控件本地化时使用的语言。
参考语言区域代码地址。例如："en"为设置本地语言为英语。
ima_load_video_timeoutint自定义超时时间。
V9.9.0.1+ 支持。单位：毫秒。
默认时间为 8000 毫秒。
platform_广告平台IDMap<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;
		}
	}
});