插屏广告
插屏广告包含 插屏半屏&插屏全屏视频 两种广告样式,下面分别介绍这类广告形态的接入文档。
插屏半屏
插屏半屏简介
插屏半屏广告是移动广告的一种常见形式,在应用开流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用(注:插屏半屏广告接入需要在开发者平台创建插屏广告,可选择横版插屏和横/竖版插屏)。
权限等级:开放
适用场景:在应用执行流程的自然停顿点,适合投放这类广告。
分类:插屏半屏广告包含小规格纯图片(弹窗)和大规格纯图片(竖屏)、插屏横屏视频、插屏竖屏视频,具体种类可以在开发者平台进行选择。
小规格纯图片(弹窗) | 大规格纯图片(竖屏) |
---|---|
插屏横屏视频 | 插屏竖屏视频 |
---|---|
主要API
UnifiedInterstitialAD
- com.qq.e.ads.interstitial2.UnifiedInterstitialAD:
插屏半屏广告入口,用于初始化并加载广告数据。
方法名 | 方法介绍 |
---|---|
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) | 构造函数 |
loadAD() | 加载插屏半屏广告 |
show() | 展示插屏半屏广告,有遮罩(展示使用loadAD()加载的广告) |
getECPMLevel() | 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串 |
getECPM() | 获取本条广告实时的eCPM价格,单位是分 |
isValid() | 广告是否有效,无效广告将无法展示 |
close() | 关闭插屏半屏广告 |
destroy() | 当不需要插屏半屏广告实例时调用此方法来主动释放资源 |
getAdPatternType() | 获取广告样式,目前只支持AdPatternType.NATIVE_VIDEO |
setMediaListener(UnifiedInterstitialMediaListener listener) | 设置监听器,监听视频广告的状态变化 |
setVideoOption(VideoOption option) | (可选方法)指定视频广告的播放配置,配置包含: 1. autoPlayPolicy,指定不同网络下的视频播放策略,可选项包括:AutoPlayPolicy.WIFI(WiFi 网络自动播放,4G 网络手动点击播放),AutoPlayPolicy.ALWAYS(WiFi 和4G 网络都自动播放),默认值为 AutoPlayPolicy.ALWAYS。 2. autoPlayMuted,指定视频自动播放时是否静音,可选项包括:true(自动播放时静音),false(自动播放时有声),默认值为 true。 注:AutoPlayPolicy.ALWAYS 的配置能够一定程度优化广告收益 3. detailPageMuted,指定视频详情页是否静音播放,可选项包括:true(视频详情页静音播放),false(视频详情页有声播放),默认值为 false。 |
setMinVideoDuration(int minVideoDuration) | 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置 |
setMaxVideoDuration(int maxVideoDuration) | 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置 |
getExtraInfo() | (4.410.1280新增)获取本条广告一些额外信息 |
UnifiedInterstitialADListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialADListener:
插屏半屏广告加载、渲染、点击状态的回调。
方法名 | 方法介绍 |
---|---|
onNoAD(AdError error) | 广告加载或展示过程中出错,AdError中包含了错误码和错误描述,具体错误码内容可参考错误码部分 |
onADReceive() | 插屏半屏广告加载完毕 |
onVideoCached() | 插屏半屏视频广告,视频素材下载完成 |
onADOpened() | 插屏半屏广告展开时回调 |
onADExposure() | 插屏半屏广告曝光时回调 |
onADClicked() | 插屏半屏广告点击时回调 |
onADClosed() | 插屏半屏广告关闭时回调 |
onADLeftApplication() | 插屏半屏广告点击离开应用时回调 |
onRenderSuccess() | 插屏半屏广告渲染成功时回调,此回调后才可以调用 show 方法 |
onRenderFail() | 插屏半屏广告渲染失败时回调 |
UnifiedInterstitialMediaListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialMediaListener:
插屏半屏视频广告播放状态回调接口,专用于带有视频素材的广告对象
方法名 | 方法介绍 |
---|---|
onVideoInit() | 视频播放 View 初始化完成 |
onVideoLoading() | 视频下载中 |
onVideoReady(long videoDuration) | 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms |
onVideoStart() | 视频开始播放 |
onVideoPause() | 视频暂停 |
onVideoComplete() | 视频播放结束,自然播放到达最后一帧时都会触发 |
onVideoError(AdError error) | 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」 |
onVideoPageOpen() | 进入视频落地页 |
onVideoPageClose() | 退出视频落地页 |
接入注意事项
- 插屏半屏广告同一条广告不能重复曝光(一次load只能show一次)
- 插屏半屏广告展示调用(show)必须在ui线程内调用
- 插屏半屏广告给开发者的回调(UnifiedInterstitialADListener)全部执行在主线程中(异步回调)
- 尽量复用广告实例,不要实例化过多的广告实例,当广告实例不再使用时务必调用destory方法进行资源释放
如果您的插屏半屏广告位支持视频,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:
- 您可以按需进行视频广告播放的个性化配置。
- 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
- 如果广告位支持视频广告,强烈建议在拉取广告前,调用
setVideoOption
设置视频广告的播放策略,有助于提高eCPM
代码接入示例
详细内容请参考压缩包中的代码示例
public class UnifiedInterstitialADActivity extends Activity implements OnClickListener,
UnifiedInterstitialADListener, CompoundButton.OnCheckedChangeListener {
private static final String TAG = UnifiedInterstitialADActivity.class.getSimpleName();
private UnifiedInterstitialAD iad;
private String posId;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_unified_interstitial_ad);
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL);
this.findViewById(R.id.loadIAD).setOnClickListener(this);
this.findViewById(R.id.showIAD).setOnClickListener(this);
this.findViewById(R.id.showIADAsPPW).setOnClickListener(this);
this.findViewById(R.id.closeIAD).setOnClickListener(this);
((CheckBox) this.findViewById(R.id.cbPos)).setOnCheckedChangeListener(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (iad != null) {
iad.destroy();
}
}
@Override
public void onClick(View v) {
switch (v.getId()) {
case R.id.loadIAD:
iad = getIAD();
setVideoOption();
iad.loadAD();
break;
case R.id.showIAD:
showAD();
break;
case R.id.showIADAsPPW:
showAsPopup();
break;
case R.id.closeIAD:
close();
break;
default:
break;
}
}
private UnifiedInterstitialAD getIAD() {
String posId = getPosID();
if (iad != null && this.posId.equals(posId)) {
return iad;
}
this.posId = posId;
if (this.iad != null) {
iad.close();
iad.destroy();
iad = null;
}
if (iad == null) {
iad = new UnifiedInterstitialAD(this, posId, this);
iad.setMediaListener(this);
}
return iad;
}
private void showAD() {
if (iad != null && iad.isValid()) {
iad.show();
} else {
Toast.makeText(this, "请加载广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
}
}
private void close() {
if (iad != null) {
iad.close();
} else {
Toast.makeText(this, "广告尚未加载 ! ", Toast.LENGTH_LONG).show();
}
}
private String getPosID() {
String posId = ((EditText) findViewById(R.id.posId)).getText().toString();
return TextUtils.isEmpty(posId) ? Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL : posId;
}
private void setVideoOption(){
VideoOption.Builder builder = new VideoOption.Builder();
VideoOption option = builder.build();
if(!btnNoOption.isChecked()){
option = builder.setAutoPlayMuted(btnMute.isChecked())
.setAutoPlayPolicy(networkSpinner.getSelectedItemPosition()).build();
}
iad.setVideoOption(option);
iad.setMaxVideoDuration(getMaxVideoDuration());
}
@Override
public void onADReceive() {
Toast.makeText(this, "广告加载成功 !建议在 onRenderSuccess 回调之后再调用 show() 展示!", Toast.LENGTH_LONG).show();
}
@Override
public void onNoAD(AdError error) {
String msg = String.format(Locale.getDefault(), "onNoAD, error code: %d, error msg: %s",
error.getErrorCode(), error.getErrorMsg());
Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}
@Override
public void onADOpened() {
Log.i(TAG, "onADOpened");
}
@Override
public void onADExposure() {
Log.i(TAG, "onADExposure");
}
@Override
public void onADClicked() {
Log.i(TAG, "onADClicked");
}
@Override
public void onADLeftApplication() {
Log.i(TAG, "onADLeftApplication");
}
@Override
public void onADClosed() {
Log.i(TAG, "onADClosed");
}
@Override
public void onRenderSuccess() {
Log.i(TAG, "onRenderSuccess,建议在此回调后再调用展示方法");
}
@Override
public void onRenderFail() {
Log.i(TAG, "onRenderFail");
}
@Override
public void onVideoInit() {
Log.i(TAG, "onVideoInit");
}
@Override
public void onVideoLoading() {
Log.i(TAG, "onVideoLoading");
}
@Override
public void onVideoReady(long videoDuration) {
Log.i(TAG, "onVideoReady, duration = " + videoDuration);
}
@Override
public void onVideoStart() {
Log.i(TAG, "onVideoStart");
}
@Override
public void onVideoPause() {
Log.i(TAG, "onVideoPause");
}
@Override
public void onVideoComplete() {
Log.i(TAG, "onVideoComplete");
}
@Override
public void onVideoError(AdError error) {
Log.i(TAG, "onVideoError, code = " + error.getErrorCode() + ", msg = " + error.getErrorMsg());
}
@Override
public void onVideoPageOpen() {
Log.i(TAG, "onVideoPageOpen");
}
@Override
public void onVideoPageClose() {
Log.i(TAG, "onVideoPageClose");
}
@Override
public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {
if (isChecked) {
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL);
} else {
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_ONLY_SMALL);
}
}
}
插屏全屏
插屏全屏简介
插屏全屏广告是移动广告的一种常见形式,在应用流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用。
权限等级:开放
适用场景:在应用执行流程的自然停顿点,适合投放这类广告。
分类:插屏全屏也分为插屏全屏图片、插屏全屏视频、奖励式插屏视频(插屏激励)。
1、插屏全屏图文
插屏全屏图文,是优量汇最新推出的广告形态。插屏图文广告在广告展示期间会引导用户上滑屏幕进行广告交互;5秒后展示关闭按钮,可关闭。
(1)若用户5秒内与屏幕无交互,则5s后图片自动上滑展示广告落地页(如有)或打开第三方应用,为用户展示广告更多内容;
(2)若用户5秒内与屏幕有交互,则图片上滑展示广告落地页(如有),帮助用户了解更多。
接入效果:可提升广告填充,提升该广告位整体收益。
备注说明:
(1)您需升级SDK至4.410及以上版本;低版本SDK将无法返回新插屏图文广告请求;
(2)插屏全屏图文广告暂不支持激励回调能力;
(3)建议您接入【图片 + 视频】混出的插屏全屏广告位,最大化提升广告收益。
权限等级:开放
适用场景:在应用执行流程的自然停顿点,适合展示这类广告。
注意事项:存量广告位请勿变更接口,新建广告位均可参考下方文档接入。
插屏全屏竖屏图文 | 插屏全屏横屏图文 |
---|---|
1.1、主要API
UnifiedInterstitialAD
- com.qq.e.ads.interstitial2.UnifiedInterstitialAD:
插屏全屏图文广告入口,用于初始化并加载广告数据。
方法名 | 方法介绍 |
---|---|
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) | 构造函数 |
loadFullScreenAD() | 加载全屏广告 |
showFullScreenAD() | 展示全屏广告 |
getECPMLevel() | 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串 |
isValid() | 广告是否有效,无效广告将无法展示 |
getAdPatternType() | 获取广告样式,区分图文或是视频广告, 2: 视频,4: 图文 |
UnifiedInterstitialADListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialADListener:
插屏全屏广告加载、渲染、点击状态的回调。
方法名 | 方法介绍 |
---|---|
onNoAD(AdError error) | 广告加载或展示过程中出错,AdError中包含了错误码和错误描述,具体错误码内容可参考错误码部分 |
onADReceive() | 插屏全屏图文广告加载完毕,此回调后才可以调用 show 方法 |
onRenderSuccess() | 插屏全屏图文广告,渲染成功 |
onRenderFail() | 插屏全屏图文广告,渲染失败 |
onADOpened() | 插屏全屏图文广告展开时回调 |
onADExposure() | 插屏全屏图文广告曝光时回调 |
onADClicked() | 插屏全屏图文广告点击时回调 |
onADClosed() | 插屏全屏图文广告关闭时回调 |
1.2、接入注意事项
- 插屏全屏图文广告使用方式与插屏全屏视频广告相同。
- 插屏全屏图文广告时MediaListener可以设置但不会回调。
1.3、代码接入示例
详细内容请参考压缩包中的代码示例
public class UnifiedInterstitialFullScreenADActivity extends Activity implements OnClickListener,
UnifiedInterstitialADListener, AdapterView.OnItemSelectedListener {
private static final String TAG = UnifiedInterstitialFullScreenADActivity.class.getSimpleName();
private UnifiedInterstitialAD iad;
private String currentPosId;
private EditText posIdEdt;
private CheckBox btnMute;
private Spinner spinner;
private PosIdArrayAdapter arrayAdapter;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_unified_interstitial_fullscreen_video_ad);
spinner = findViewById(R.id.id_spinner);
arrayAdapter = new PosIdArrayAdapter(this, android.R.layout.simple_spinner_item, getResources().getStringArray(R.array.unified_interstitial_video));
arrayAdapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
btnMute = findViewById(R.id.btn_mute);
btnMute.setChecked(true);
spinner.setAdapter(arrayAdapter);
spinner.setOnItemSelectedListener(this);
posIdEdt = findViewById(R.id.posId);
posIdEdt.setText(PositionId.UNIFIED_VIDEO_PICTURE_ID_LARGE);
this.findViewById(R.id.loadIADFullScreen).setOnClickListener(this);
this.findViewById(R.id.showIADFullScreen).setOnClickListener(this);
this.findViewById(R.id.isAdValid).setOnClickListener(this);
}
@Override
public void onClick(View v) {
switch (v.getId()) {
case R.id.loadIADFullScreen:
iad = getIAD();
setVideoOption();
iad.loadFullScreenAD();
break;
case R.id.showIADFullScreen:
showFullScreenVideoAD();
break;
case R.id.isAdValid:
isAdValid();
break;
default:
break;
}
}
private void isAdValid() {
if (iad == null) {
Toast.makeText(this, "请加载广告后再进行校验 ! ", Toast.LENGTH_LONG).show();
} else {
Toast.makeText(this, "广告" + (iad.isValid() ? "有效" : "无效"), Toast.LENGTH_LONG).show();
}
}
private UnifiedInterstitialAD getIAD() {
String posId = posIdEdt.getText().toString();
if (!posId.equals(currentPosId) || iad == null) {
iad = new UnifiedInterstitialAD(this, posId, this);
ServerSideVerificationOptions options = new ServerSideVerificationOptions.Builder()
.setCustomData("APP's custom data") // 设置插屏全屏视频服务端验证的自定义信息
.setUserId("APP's user id for server verify") // 设置服务端验证的用户信息
.build();
iad.setServerSideVerificationOptions(options);
currentPosId = posId;
}
return iad;
}
private void showFullScreenVideoAD() {
if (iad == null) {
Toast.makeText(this, "请加载广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
return;
}
if (iad.isValid()) {
iad.showFullScreenAD(this);
} else {
Toast.makeText(this, "广告已经展示或未成功拉取,请拉取广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
}
}
@Override
public void onADReceive() {
Toast.makeText(this, "广告加载成功 ! ", Toast.LENGTH_LONG).show();
// onADReceive之后才可调用getECPM()
Log.d(TAG, "eCPMLevel = " + iad.getECPMLevel() + ", ECPM: " + iad.getECPM() + ", videoduration=" + iad.getVideoDuration());
if (DownloadConfirmHelper.USE_CUSTOM_DIALOG) {
iad.setDownloadConfirmListener(DownloadConfirmHelper.DOWNLOAD_CONFIRM_LISTENER);
}
}
@Override
public void onNoAD(AdError error) {
String msg = String.format(Locale.getDefault(), "onNoAD, error code: %d, error msg: %s",
error.getErrorCode(), error.getErrorMsg());
Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}
@Override
public void onADOpened() {
Log.i(TAG, "onADOpened");
}
@Override
public void onADExposure() {
Log.i(TAG, "onADExposure");
}
@Override
public void onADClicked() {
Log.i(TAG, "onADClicked");
}
@Override
public void onADClosed() {
Log.i(TAG, "onADClosed");
}
@Override
public void onRenderSuccess() {
Log.i(TAG, "onRenderSuccess");
}
@Override
public void onRenderFail() {
Log.i(TAG, "onRenderFail");
}
@Override
public void onItemSelected(AdapterView<?> parent, View view, int position, long id) {
arrayAdapter.setSelectedPos(position);
posIdEdt.setText(getResources().getStringArray(R.array.unified_interstitial_video_value)[position]);
}
@Override
public void onNothingSelected(AdapterView<?> parent) {
}
}
2、插屏全屏视频
插屏全屏视频广告是移动广告的一种常见形式,在应用流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用。
竖版 | 横版 |
---|---|
2.1、主要API
UnifiedInterstitialAD
- com.qq.e.ads.interstitial2.UnifiedInterstitialAD:
插屏全屏视频广告入口,用于初始化并加载广告数据。
方法名 | 方法介绍 |
---|---|
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) | 构造函数 |
loadFullScreenAD() | 加载全屏广告(目前只支持全屏视频广告) |
showFullScreenAD(Activity activity) | activity为当前loadAd并展示的页面,展示全屏广告(目前只支持全屏视频广告,展示使用loadFullScreenAD()方法加载的广告) |
getECPMLevel() | 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串 |
isValid() | 广告是否有效,无效广告将无法展示 |
close() | (4.530.1400新增)关闭插屏全屏广告 |
getAdPatternType() | 获取广告样式,目前只支持AdPatternType.NATIVE_VIDEO |
setMediaListener(UnifiedInterstitialMediaListener listener) | 设置监听器,监听视频广告的状态变化 |
setVideoOption(VideoOption option) | (可选方法)指定视频广告的播放配置,配置包含: 1. autoPlayPolicy,指定不同网络下的视频播放策略,可选项包括:AutoPlayPolicy.WIFI(WiFi 网络自动播放,4G 网络手动点击播放),AutoPlayPolicy.ALWAYS(WiFi 和4G 网络都自动播放),默认值为 AutoPlayPolicy.ALWAYS。 2. autoPlayMuted,指定视频自动播放时是否静音,可选项包括:true(自动播放时静音),false(自动播放时有声),默认值为 true。 注:AutoPlayPolicy.ALWAYS 的配置能够一定程度优化广告收益 3. detailPageMuted,指定视频详情页是否静音播放,可选项包括:true(视频详情页静音播放),false(视频详情页有声播放),默认值为 false。 |
setMinVideoDuration(int minVideoDuration) | 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效 |
setMaxVideoDuration(int maxVideoDuration) | 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效 |
getExtraInfo() | (4.410.1280新增)获取本条广告一些额外信息 |
UnifiedInterstitialADListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialADListener:
插屏全屏视频广告加载、渲染、点击状态的回调。
方法名 | 方法介绍 |
---|---|
onNoAD(AdError error) | 广告加载或展示过程中出错,AdError中包含了错误码和错误描述,具体错误码内容可参考错误码部分 |
onADReceive() | 插屏全屏视频广告加载完毕,此回调后才可以调用 show 方法 |
onVideoCached() | 插屏全屏视频视频广告,视频素材下载完成 |
onRenderSuccess() | 插屏全屏视频视频广告,渲染成功 |
onRenderFail() | 插屏全屏视频视频广告,渲染失败 |
onADOpened() | 插屏全屏视频广告展开时回调 |
onADExposure() | 插屏全屏视频广告曝光时回调 |
onADClicked() | 插屏全屏视频广告点击时回调 |
onADClosed() | 插屏全屏视频广告关闭时回调 |
onADLeftApplication() | 插屏全屏视频广告点击离开应用时回调 |
UnifiedInterstitialMediaListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialMediaListener:
插屏全屏视频视频广告播放状态回调接口
方法名 | 方法介绍 |
---|---|
onVideoInit() | 视频播放 View 初始化完成 |
onVideoLoading() | 视频下载中 |
onVideoReady(long videoDuration) | 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms |
onVideoStart() | 视频开始播放 |
onVideoPause() | 视频暂停 |
onVideoComplete() | 视频播放结束,自然播放到达最后一帧时都会触发 |
onVideoError(AdError error) | 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」 |
2.2、接入注意事项
- 插屏全屏视频广告同一条广告不能重复曝光(一次load只能show一次)
- 插屏全屏视频广告展示调用(showFullScreenAD)必须在ui线程内调用
- 插屏全屏视频广告给开发者的回调(UnifiedInterstitialADListener)全部执行在主线程中(异步回调)
- 尽量复用广告实例,不要实例化过多的广告实例
对于插屏全屏视频广告位,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:
- 您可以按需进行视频广告播放的个性化配置。
- 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
- 如果广告位支持视频广告,强烈建议在拉取广告前,调用
setVideoOption
设置视频广告的播放策略,有助于提高eCPM
2.3、代码接入示例
详细内容请参考压缩包中的代码示例
public class UnifiedInterstitialADActivity extends Activity implements OnClickListener,
UnifiedInterstitialADListener, CompoundButton.OnCheckedChangeListener {
private static final String TAG = UnifiedInterstitialADActivity.class.getSimpleName();
private UnifiedInterstitialAD iad;
private String posId;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_unified_interstitial_ad);
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL);
this.findViewById(R.id.loadIAD).setOnClickListener(this);
this.findViewById(R.id.showIAD).setOnClickListener(this);
this.findViewById(R.id.closeIAD).setOnClickListener(this);
((CheckBox) this.findViewById(R.id.cbPos)).setOnCheckedChangeListener(this);
}
@Override
public void onClick(View v) {
switch (v.getId()) {
case R.id.loadIAD:
iad = getIAD();
setVideoOption();
iad.loadFullScreenAD();
break;
case R.id.showIAD:
showAD();
break;
case R.id.closeIAD:
close();
break;
default:
break;
}
}
private UnifiedInterstitialAD getIAD() {
String posId = getPosID();
if (iad != null && this.posId.equals(posId)) {
return iad;
}
this.posId = posId;
if (this.iad != null) {
iad.close();
iad.destroy();
iad = null;
}
if (iad == null) {
iad = new UnifiedInterstitialAD(this, posId, this);
}
return iad;
}
private void showAD() {
if (iad != null && iad.isValid()) {
iad.showFullScreenAD();
} else {
Toast.makeText(this, "请加载广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
}
}
private void close() {
if (iad != null) {
iad.close();
} else {
Toast.makeText(this, "广告尚未加载 ! ", Toast.LENGTH_LONG).show();
}
}
private String getPosID() {
String posId = ((EditText) findViewById(R.id.posId)).getText().toString();
return TextUtils.isEmpty(posId) ? Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL : posId;
}
private void setVideoOption(){
VideoOption.Builder builder = new VideoOption.Builder();
VideoOption option = builder.build();
if(!btnNoOption.isChecked()){
option = builder.setAutoPlayMuted(btnMute.isChecked())
.setAutoPlayPolicy(networkSpinner.getSelectedItemPosition()).build();
}
iad.setVideoOption(option);
iad.setMaxVideoDuration(getMaxVideoDuration());
}
@Override
public void onADReceive() {
Toast.makeText(this, "广告加载成功 ! ", Toast.LENGTH_LONG).show();
iad.setMediaListener(this);
}
@Override
public void onNoAD(AdError error) {
String msg = String.format(Locale.getDefault(), "onNoAD, error code: %d, error msg: %s",
error.getErrorCode(), error.getErrorMsg());
Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}
@Override
public void onADOpened() {
Log.i(TAG, "onADOpened");
}
@Override
public void onADExposure() {
Log.i(TAG, "onADExposure");
}
@Override
public void onADClicked() {
Log.i(TAG, "onADClicked");
}
@Override
public void onADLeftApplication() {
Log.i(TAG, "onADLeftApplication");
}
@Override
public void onADClosed() {
Log.i(TAG, "onADClosed");
}
@Override
public void onRenderSuccess() {
Log.i(TAG, "onRenderSuccess");
}
@Override
public void onRenderFail() {
Log.i(TAG, "onRenderFail");
}
@Override
public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {
if (isChecked) {
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_LARGE_SMALL);
} else {
((EditText) findViewById(R.id.posId)).setText(Constants.UNIFIED_INTERSTITIAL_ID_ONLY_SMALL);
}
}
}
3、奖励式插屏全屏视频(插屏激励)
奖励式插屏全屏视频,是优量汇最新推出的广告形态。
奖励式插屏视频在视频播放5s后展示关闭按钮,可关闭;但在关闭展示的同时,增加引导提示「再观看X秒即可获得额外奖励」:
(1)用户如感兴趣,完成视频观看:开发者需针对满足观看的用户,派发额外的奖励,如系统内的金币,生命值等。
(2)用户如不感兴趣,不完成视频观看:可随时点击关闭按钮,退出广告,同普通插屏全屏视频。
接入效果:奖励式插屏,可延长视频播放时间,提升该广告位eCPM和整体收益。
备注说明:选中该样式时,您务必针对满足观看的用户,派发额外奖励,如系统内的金币,生命值等。
适用场景:在应用执行流程的自然停顿点,适合展示这类广告。
注意事项:存量广告位请勿变更接口,新建广告位均可参考下方文档接入。
支持版本:Android SDK 4.390及以上。
前5秒 | 后5秒 |
---|---|
3.1、主要API
UnifiedInterstitialAD
- com.qq.e.ads.interstitial2.UnifiedInterstitialAD:
奖励式插屏全屏视频广告入口,用于初始化并加载广告数据。
方法名 | 方法介绍 |
---|---|
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) | 构造函数 |
loadFullScreenAD() | 加载全屏广告(目前只支持全屏视频广告) |
showFullScreenAD() | 展示全屏广告(目前只支持全屏视频广告,展示使用loadFullScreenAD()方法加载的广告) |
getECPMLevel() | 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串 |
getAdPatternType() | 获取广告样式,目前只支持AdPatternType.NATIVE_VIDEO |
setMediaListener(UnifiedInterstitialMediaListener listener) | 设置监听器,监听视频广告的状态变化 |
setRewardListener(ADRewardListener listener) | 设置奖励监听 |
setVideoOption(VideoOption option) | (可选方法)指定视频广告的播放配置,配置包含: 1. autoPlayPolicy,指定不同网络下的视频播放策略,可选项包括:AutoPlayPolicy.WIFI(WiFi 网络自动播放,4G 网络手动点击播放),AutoPlayPolicy.ALWAYS(WiFi 和4G 网络都自动播放),默认值为 AutoPlayPolicy.ALWAYS。 2. autoPlayMuted,指定视频自动播放时是否静音,可选项包括:true(自动播放时静音),false(自动播放时有声),默认值为 true。 注:AutoPlayPolicy.ALWAYS 的配置能够一定程度优化广告收益 3. detailPageMuted,指定视频详情页是否静音播放,可选项包括:true(视频详情页静音播放),false(视频详情页有声播放),默认值为 false。 |
setMinVideoDuration(int minVideoDuration) | 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效 |
setMaxVideoDuration(int maxVideoDuration) | 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效 |
isValid() | 广告是否有效,无效广告将无法展示 |
UnifiedInterstitialADListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialADListener:
插屏全屏视频广告加载、渲染、点击状态的回调。
方法名 | 方法介绍 |
---|---|
onNoAD(AdError error) | 广告加载或展示过程中出错,AdError中包含了错误码和错误描述,具体错误码内容可参考错误码部分 |
onADReceive() | 插屏全屏视频广告加载完毕,此回调后才可以调用 show 方法 |
onVideoCached() | 插屏全屏视频视频广告,视频素材下载完成 |
onRenderSuccess() | 插屏全屏视频视频广告,渲染成功 |
onRenderFail() | 插屏全屏视频视频广告,渲染失败 |
onADOpened() | 插屏全屏视频广告展开时回调 |
onADExposure() | 插屏全屏视频广告曝光时回调 |
onADClicked() | 插屏全屏视频广告点击时回调 |
onADClosed() | 插屏全屏视频广告关闭时回调 |
onADLeftApplication() | 插屏全屏视频广告点击离开应用时回调 |
UnifiedInterstitialMediaListener
- com.qq.e.ads.interstitial2.UnifiedInterstitialMediaListener:
插屏全屏视频视频广告播放状态回调接口
方法名 | 方法介绍 |
---|---|
onVideoInit() | 视频播放 View 初始化完成 |
onVideoLoading() | 视频下载中 |
onVideoReady(long videoDuration) | 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms |
onVideoStart() | 视频开始播放 |
onVideoPause() | 视频暂停 |
onVideoComplete() | 视频播放结束,自然播放到达最后一帧时都会触发 |
onVideoError(AdError error) | 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」 |
3.2、接入注意事项
- 奖励式插屏全屏视频广告使用方式与插屏全屏视频广告相同。
- 设置奖励回调才可以监听到获取奖励事件。
对于奖励式插屏全屏视频广告位,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:
- 您可以按需进行视频广告播放的个性化配置。
- 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
- 如果广告位支持视频广告,强烈建议在拉取广告前,调用
setVideoOption
设置视频广告的播放策略,有助于提高eCPM
3.3、代码接入示例
详细内容请参考压缩包中的代码示例
public class UnifiedInterstitialFullScreenADActivity extends Activity implements OnClickListener,
UnifiedInterstitialADListener, UnifiedInterstitialMediaListener, ADRewardListener, AdapterView.OnItemSelectedListener {
private static final String TAG = UnifiedInterstitialFullScreenADActivity.class.getSimpleName();
private UnifiedInterstitialAD iad;
private String currentPosId;
private EditText posIdEdt;
private CheckBox btnMute;
private Spinner spinner;
private PosIdArrayAdapter arrayAdapter;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_unified_interstitial_fullscreen_video_ad);
spinner = findViewById(R.id.id_spinner);
arrayAdapter = new PosIdArrayAdapter(this, android.R.layout.simple_spinner_item, getResources().getStringArray(R.array.unified_interstitial_video));
arrayAdapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
btnMute = findViewById(R.id.btn_mute);
btnMute.setChecked(true);
spinner.setAdapter(arrayAdapter);
spinner.setOnItemSelectedListener(this);
posIdEdt = findViewById(R.id.posId);
posIdEdt.setText(PositionId.UNIFIED_VIDEO_PICTURE_ID_LARGE);
this.findViewById(R.id.loadIADFullScreen).setOnClickListener(this);
this.findViewById(R.id.showIADFullScreen).setOnClickListener(this);
this.findViewById(R.id.isAdValid).setOnClickListener(this);
}
@Override
public void onClick(View v) {
switch (v.getId()) {
case R.id.loadIADFullScreen:
iad = getIAD();
setVideoOption();
iad.loadFullScreenAD();
break;
case R.id.showIADFullScreen:
showFullScreenVideoAD();
break;
case R.id.isAdValid:
isAdValid();
break;
default:
break;
}
}
private void isAdValid() {
if (iad == null) {
Toast.makeText(this, "请加载广告后再进行校验 ! ", Toast.LENGTH_LONG).show();
} else {
Toast.makeText(this, "广告" + (iad.isValid() ? "有效" : "无效"), Toast.LENGTH_LONG).show();
}
}
private void setVideoOption() {
VideoOption.Builder builder = new VideoOption.Builder();
VideoOption option = builder.setAutoPlayMuted(btnMute.isChecked()).build();
iad.setVideoOption(option);
// 如果支持奖励,最大、最小视频时长设置将不生效
iad.setMinVideoDuration(getMinVideoDuration());
iad.setMaxVideoDuration(getMaxVideoDuration());
}
private UnifiedInterstitialAD getIAD() {
String posId = posIdEdt.getText().toString();
if (!posId.equals(currentPosId) || iad == null) {
iad = new UnifiedInterstitialAD(this, posId, this);
ServerSideVerificationOptions options = new ServerSideVerificationOptions.Builder()
.setCustomData("APP's custom data") // 设置插屏全屏视频服务端验证的自定义信息
.setUserId("APP's user id for server verify") // 设置服务端验证的用户信息
.build();
iad.setServerSideVerificationOptions(options);
currentPosId = posId;
}
return iad;
}
private void showFullScreenVideoAD() {
if (iad == null) {
Toast.makeText(this, "请加载广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
return;
}
if (iad.isValid()) {
iad.showFullScreenAD(this);
} else {
Toast.makeText(this, "广告已经展示或未成功拉取,请拉取广告后再进行展示 ! ", Toast.LENGTH_LONG).show();
}
}
@Override
public void onADReceive() {
Toast.makeText(this, "广告加载成功 ! ", Toast.LENGTH_LONG).show();
iad.setMediaListener(this);
// 如果支持奖励,设置ADRewardListener接收onReward回调
iad.setRewardListener(this);
// onADReceive之后才可调用getECPM()
Log.d(TAG, "eCPMLevel = " + iad.getECPMLevel() + ", ECPM: " + iad.getECPM() + ", videoduration=" + iad.getVideoDuration());
if (DownloadConfirmHelper.USE_CUSTOM_DIALOG) {
iad.setDownloadConfirmListener(DownloadConfirmHelper.DOWNLOAD_CONFIRM_LISTENER);
}
}
@Override
public void onVideoCached() {
// 视频素材加载完成,在此时调用iad.show()视频广告不会有进度条。
Log.i(TAG, "onVideoCached");
}
@Override
public void onNoAD(AdError error) {
String msg = String.format(Locale.getDefault(), "onNoAD, error code: %d, error msg: %s",
error.getErrorCode(), error.getErrorMsg());
Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}
@Override
public void onADOpened() {
Log.i(TAG, "onADOpened");
}
@Override
public void onADExposure() {
Log.i(TAG, "onADExposure");
}
@Override
public void onADClicked() {
Log.i(TAG, "onADClicked");
}
@Override
public void onReward(Map<String, Object> map) {
Log.i(TAG, "onReward " + map.get(ServerSideVerificationOptions.TRANS_ID)); // 获取服务端验证的唯一 ID
}
@Override
public void onADLeftApplication() {
Log.i(TAG, "onADLeftApplication");
}
@Override
public void onADClosed() {
Log.i(TAG, "onADClosed");
}
@Override
public void onRenderSuccess() {
Log.i(TAG, "onRenderSuccess");
}
@Override
public void onRenderFail() {
Log.i(TAG, "onRenderFail");
}
@Override
public void onVideoInit() {
Log.i(TAG, "onVideoInit");
}
@Override
public void onVideoLoading() {
Log.i(TAG, "onVideoLoading");
}
@Override
public void onVideoReady(long videoDuration) {
Log.i(TAG, "onVideoReady, duration = " + videoDuration);
}
@Override
public void onVideoStart() {
Log.i(TAG, "onVideoStart");
}
@Override
public void onVideoPause() {
Log.i(TAG, "onVideoPause");
}
@Override
public void onVideoComplete() {
Log.i(TAG, "onVideoComplete");
}
@Override
public void onVideoError(AdError error) {
String msg = "onVideoError, code = " + error.getErrorCode() + ", msg = " + error.getErrorMsg();
Log.i(TAG, msg);
Toast.makeText(getApplicationContext(), msg, Toast.LENGTH_LONG).show();
}
@Override
public void onVideoPageOpen() {
Log.i(TAG, "onVideoPageOpen");
}
@Override
public void onVideoPageClose() {
Log.i(TAG, "onVideoPageClose");
}
private int getMinVideoDuration() {
if (((CheckBox) findViewById(R.id.cbMinVideoDuration)).isChecked()) {
try {
int rst =
Integer.parseInt(((EditText) findViewById(R.id.etMinVideoDuration)).getText().toString());
if (rst > 0) {
return rst;
} else {
Toast.makeText(getApplicationContext(), "最小视频时长输入须大于0!", Toast.LENGTH_LONG).show();
}
} catch (NumberFormatException e) {
Toast.makeText(getApplicationContext(), "最小视频时长输入不是整数!", Toast.LENGTH_LONG).show();
}
}
return 0;
}
private int getMaxVideoDuration() {
if (((CheckBox) findViewById(R.id.cbMaxVideoDuration)).isChecked()) {
try {
int rst = Integer.parseInt(((EditText) findViewById(R.id.etMaxVideoDuration)).getText().toString());
if (rst >= VIDEO_DURATION_SETTING_MIN && rst <= VIDEO_DURATION_SETTING_MAX) {
return rst;
} else {
String msg = String.format("最大视频时长输入不在有效区间[%d,%d]内", VIDEO_DURATION_SETTING_MIN, VIDEO_DURATION_SETTING_MAX);
Toast.makeText(getApplicationContext(), msg, Toast.LENGTH_LONG).show();
}
} catch (NumberFormatException e) {
Toast.makeText(getApplicationContext(), "最大视频时长输入不是整数!", Toast.LENGTH_LONG).show();
}
}
return 0;
}
@Override
public void onItemSelected(AdapterView<?> parent, View view, int position, long id) {
arrayAdapter.setSelectedPos(position);
posIdEdt.setText(getResources().getStringArray(R.array.unified_interstitial_video_value)[position]);
}
@Override
public void onNothingSelected(AdapterView<?> parent) {
}
}