Android iOS Unity JS API Media API 常见问题

插屏广告

插屏广告包含 插屏半屏&插屏全屏视频 两种广告样式,下面分别介绍这类广告形态的接入文档。

插屏半屏

插屏半屏简介

插屏半屏广告是移动广告的一种常见形式,在应用开流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用(注:插屏半屏广告接入需要在开发者平台创建插屏广告,可选择横版插屏和横/竖版插屏)。

权限等级:开放

适用场景:在应用执行流程的自然停顿点,适合投放这类广告。

注意事项如您正在使用模板插屏接口,请尽快按该文档更新接入方式,模板插屏接口将很快废弃。请尽快更新至4.370.1240版本及以上。

分类:插屏半屏广告包含小规格纯图片(弹窗)和大规格纯图片(竖屏)、插屏横屏视频、插屏竖屏视频,具体种类可以在开发者平台进行选择。

小规格纯图片(弹窗) 大规格纯图片(竖屏)
插屏横屏视频 插屏竖屏视频

主要API

加了删除线的方法即将废弃。

UnifiedInterstitialAD

方法名 方法介绍
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) 构造函数
UnifiedInterstitialAD(final Activity activity, final String appID, final String posID,final UnifiedInterstitialADListener listener) 构造函数
loadAD() 加载插屏半屏广告
show() 展示插屏半屏广告,有遮罩(展示使用loadAD()加载的广告)
showAsPopupWindow() 展示插屏半屏广告,无遮罩(展示使用loadAD()加载的广告)
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
getECPM() 获取本条广告实时的eCPM价格,单位是分;权限提示:调用此接口前,需要向优量汇运营接口人申请实时竞价权限,当无权限调用该接口时,SDK会返回错误码-1
isValid() 广告是否有效,无效广告将无法展示
close() 关闭插屏半屏广告
destroy() 当不需要插屏半屏广告实例时调用此方法来主动释放资源

UnifiedInterstitialADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息
onADReceive() 插屏半屏广告加载完毕,此回调后才可以调用 show 方法
onVideoCached() 插屏半屏视频广告,视频素材下载完成
onADOpened() 插屏半屏广告展开时回调
onADExposure() 插屏半屏广告曝光时回调
onADClicked() 插屏半屏广告点击时回调
onADClosed() 插屏半屏广告关闭时回调
onADLeftApplication() 插屏半屏广告点击离开应用时回调
getAdPatternType() 获取广告样式,目前只支持AdPatternType.NATIVE_VIDEO
onRenderSuccess() 插屏半屏广告渲染成功时回调
onRenderFail() 插屏半屏广告渲染失败时回调
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。
setVideoPlayPolicy(int policy) 设置本次拉取的视频广告,从用户角度看到的视频播放策略;可选项包括自VideoOption.VideoPlayPolicy.AUTO(在用户看来,视频广告是自动播放的)和VideoOption.VideoPlayPolicy.MANUAL(在用户看来,视频广告是手动播放的);如果广告位支持视频,强烈建议调用此接口设置视频广告的播放策略,有助于提高eCPM值;如果广告位不支持视频,忽略本接口
setMinVideoDuration(int minVideoDuration) 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置
setMaxVideoDuration(int maxVideoDuration) 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置

UnifiedInterstitialMediaListener

方法名 方法介绍
onVideoInit() 视频播放 View 初始化完成
onVideoLoading() 视频下载中
onVideoReady(long videoDuration) 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms
onVideoStart() 视频开始播放
onVideoPause() 视频暂停
onVideoComplete() 视频播放结束,自然播放到达最后一帧时都会触发
onVideoError(AdError error) 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」
onVideoPageOpen() 进入视频落地页
onVideoPageClose() 退出视频落地页

接入注意事项

  1. 插屏半屏广告同一条广告不能重复曝光(一次load只能show一次)
  2. 插屏半屏广告展示调用(show/showAsPopupWindow)必须在ui线程内调用
  3. 插屏半屏广告给开发者的回调(UnifiedInterstitialADListener)全部执行在主线程中(异步回调)
  4. 尽量复用广告实例,不要实例化过多的广告实例,当广告实例不再使用时务必调用destory方法进行资源释放

如果您的插屏半屏广告位支持视频,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:

  1. 您可以按需进行视频广告播放的个性化配置。
  2. 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
  3. 如果广告位支持视频广告,强烈建议在拉取广告前,调用setVideoPlayPolicy设置视频广告的播放策略,有助于提高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 showAsPopup() {
    if (iad != null && iad.isValid()) {
      iad.showAsPopupWindow();
    } 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());

    /**
     * 如果广告位支持视频广告,强烈建议在调用loadData请求广告前调用setVideoPlayPolicy,有助于提高视频广告的eCPM值 <br/>
     * 如果广告位仅支持图文广告,则无需调用
     */

    /**
     * 设置本次拉取的视频广告,从用户角度看到的视频播放策略<p/>
     *
     * "用户角度"特指用户看到的情况,并非SDK是否自动播放,与自动播放策略AutoPlayPolicy的取值并非一一对应 <br/>
     *
     * 如自动播放策略为AutoPlayPolicy.WIFI,但此时用户网络为4G环境,在用户看来就是手工播放的
     */
    iad.setVideoPlayPolicy(NativeExpressDemoActivity.getVideoPlayPolicy(option.getAutoPlayPolicy(), this));
  }

  @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);
    }
  }
}

插屏全屏

插屏全屏简介

插屏全屏广告是移动广告的一种常见形式,在应用流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用。

权限等级:开放

适用场景:在应用执行流程的自然停顿点,适合投放这类广告。

注意事项如您正在使用模板插屏接口,请尽快按该文档更新接入方式,模板插屏接口将很快废弃。请尽快更新至4.370.1240版本及以上。

分类:插屏全屏也分为插屏全屏图片、插屏全屏视频、奖励式插屏视频(插屏激励)。

1、插屏全屏图文

插屏全屏图文,是优量汇最新推出的广告形态。插屏图文广告在广告展示期间会引导用户上滑屏幕进行广告交互;5秒后展示关闭按钮,可关闭。

(1)若用户5秒内与屏幕无交互,则5s后图片自动上滑展示广告落地页(如有)或打开第三方应用,为用户展示广告更多内容;

(2)若用户5秒内与屏幕有交互,则图片上滑展示广告落地页(如有),帮助用户了解更多。

接入效果:可提升广告填充,提升该广告位整体收益。
备注说明

(1)您需升级SDK至4.410及以上版本;低版本SDK将无法返回新插屏图文广告请求;

(2)插屏全屏图文广告暂不支持激励回调能力;

(3)建议您接入【图片 + 视频】混出的插屏全屏广告位,最大化提升广告收益。

权限等级:开放

适用场景:在应用执行流程的自然停顿点,适合展示这类广告。

注意事项:存量广告位请勿变更接口,新建广告位均可参考下方文档接入。

插屏全屏竖屏图文 插屏全屏横屏图文

1.1、主要API

加了删除线的方法即将废弃。

UnifiedInterstitialAD

方法名 方法介绍
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) 构造函数
UnifiedInterstitialAD(final Activity activity, final String appID, final String posID,final UnifiedInterstitialADListener listener) 构造函数
loadFullScreenAD() 加载全屏广告
showFullScreenAD() 展示全屏广告
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
isValid() 广告是否有效,无效广告将无法展示

UnifiedInterstitialADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息
onADReceive() 插屏全屏图文广告加载完毕,此回调后才可以调用 show 方法
onRenderSuccess() 插屏全屏图文广告,渲染成功
onRenderFail() 插屏全屏图文广告,渲染失败
onADOpened() 插屏全屏图文广告展开时回调
onADExposure() 插屏全屏图文广告曝光时回调
onADClicked() 插屏全屏图文广告点击时回调
onADClosed() 插屏全屏图文广告关闭时回调
getAdPatternType() 获取广告样式,区分图文或是视频广告

1.2、接入注意事项

  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

方法名 方法介绍
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) 构造函数
UnifiedInterstitialAD(final Activity activity, final String appID, final String posID,final UnifiedInterstitialADListener listener) 构造函数
loadFullScreenAD() 加载全屏广告(目前只支持全屏视频广告)
showFullScreenAD() 展示全屏广告(目前只支持全屏视频广告,展示使用loadFullScreenAD()方法加载的广告)
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
isValid() 广告是否有效,无效广告将无法展示

UnifiedInterstitialADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息
onADReceive() 插屏全屏视频广告加载完毕,此回调后才可以调用 show 方法
onVideoCached() 插屏全屏视频视频广告,视频素材下载完成
onRenderSuccess() 插屏全屏视频视频广告,渲染成功
onRenderFail() 插屏全屏视频视频广告,渲染失败
onADOpened() 插屏全屏视频广告展开时回调
onADExposure() 插屏全屏视频广告曝光时回调
onADClicked() 插屏全屏视频广告点击时回调
onADClosed() 插屏全屏视频广告关闭时回调
onADLeftApplication() 插屏全屏视频广告点击离开应用时回调
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。
setVideoPlayPolicy(int policy) 设置本次拉取的视频广告,从用户角度看到的视频播放策略;可选项包括自VideoOption.VideoPlayPolicy.AUTO(在用户看来,视频广告是自动播放的)和VideoOption.VideoPlayPolicy.MANUAL(在用户看来,视频广告是手动播放的);插屏全屏视频广告,强烈建议调用此接口设置视频广告的播放策略,有助于提高eCPM值
setMinVideoDuration(int minVideoDuration) 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效
setMaxVideoDuration(int maxVideoDuration) 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效

UnifiedInterstitialMediaListener

方法名 方法介绍
onVideoInit() 视频播放 View 初始化完成
onVideoLoading() 视频下载中
onVideoReady(long videoDuration) 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms
onVideoStart() 视频开始播放
onVideoPause() 视频暂停
onVideoComplete() 视频播放结束,自然播放到达最后一帧时都会触发
onVideoError(AdError error) 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」

2.2、接入注意事项

  1. 插屏全屏视频广告同一条广告不能重复曝光(一次load只能show一次)
  2. 插屏全屏视频广告展示调用(showFullScreenAD)必须在ui线程内调用
  3. 插屏全屏视频广告给开发者的回调(UnifiedInterstitialADListener)全部执行在主线程中(异步回调)
  4. 尽量复用广告实例,不要实例化过多的广告实例

对于插屏全屏视频广告位,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:

  1. 您可以按需进行视频广告播放的个性化配置。
  2. 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
  3. 如果广告位支持视频广告,强烈建议在拉取广告前,调用setVideoPlayPolicy设置视频广告的播放策略,有助于提高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());

    /**
     * 插屏全屏视频广告,强烈建议在调用loadFullScreenAD请求广告前调用setVideoPlayPolicy,有助于提高视频广告的eCPM值 <br/>
     */

    /**
     * 设置本次拉取的视频广告,从用户角度看到的视频播放策略<p/>
     *
     * "用户角度"特指用户看到的情况,并非SDK是否自动播放,与自动播放策略AutoPlayPolicy的取值并非一一对应 <br/>
     *
     * 如自动播放策略为AutoPlayPolicy.WIFI,但此时用户网络为4G环境,在用户看来就是手工播放的
     */
    iad.setVideoPlayPolicy(NativeExpressDemoActivity.getVideoPlayPolicy(option.getAutoPlayPolicy(), this));
  }

  @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及以上。

3.1、主要API

加了删除线的方法即将废弃。

UnifiedInterstitialAD

方法名 方法介绍
UnifiedInterstitialAD(final Activity activity, final String posID,final UnifiedInterstitialADListener listener) 构造函数
UnifiedInterstitialAD(final Activity activity, final String appID, final String posID,final UnifiedInterstitialADListener listener) 构造函数
loadFullScreenAD() 加载全屏广告(目前只支持全屏视频广告)
showFullScreenAD() 展示全屏广告(目前只支持全屏视频广告,展示使用loadFullScreenAD()方法加载的广告)
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
isValid() 广告是否有效,无效广告将无法展示

UnifiedInterstitialADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息
onADReceive() 插屏全屏视频广告加载完毕,此回调后才可以调用 show 方法
onVideoCached() 插屏全屏视频视频广告,视频素材下载完成
onRenderSuccess() 插屏全屏视频视频广告,渲染成功
onRenderFail() 插屏全屏视频视频广告,渲染失败
onADOpened() 插屏全屏视频广告展开时回调
onADExposure() 插屏全屏视频广告曝光时回调
onADClicked() 插屏全屏视频广告点击时回调
onADClosed() 插屏全屏视频广告关闭时回调
onADLeftApplication() 插屏全屏视频广告点击离开应用时回调
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。
setVideoPlayPolicy(int policy) 设置本次拉取的视频广告,从用户角度看到的视频播放策略;可选项包括自VideoOption.VideoPlayPolicy.AUTO(在用户看来,视频广告是自动播放的)和VideoOption.VideoPlayPolicy.MANUAL(在用户看来,视频广告是手动播放的);插屏全屏视频广告,强烈建议调用此接口设置视频广告的播放策略,有助于提高eCPM值
setMinVideoDuration(int minVideoDuration) 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效
setMaxVideoDuration(int maxVideoDuration) 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置;支持奖励时该设置无效

UnifiedInterstitialMediaListener

方法名 方法介绍
onVideoInit() 视频播放 View 初始化完成
onVideoLoading() 视频下载中
onVideoReady(long videoDuration) 视频播放器初始化完成,准备好可以播放了,videoDuration 是视频素材的时间长度,单位为 ms
onVideoStart() 视频开始播放
onVideoPause() 视频暂停
onVideoComplete() 视频播放结束,自然播放到达最后一帧时都会触发
onVideoError(AdError error) 视频播放时出现错误,error 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」

3.2、接入注意事项

  1. 奖励式插屏全屏视频广告使用方式与插屏全屏视频广告相同。
  2. 设置奖励回调才可以监听到获取奖励事件。

对于奖励式插屏全屏视频广告位,您会在新建广告位时在广告素材栏看到视频选项。您需要注意以下几点:

  1. 您可以按需进行视频广告播放的个性化配置。
  2. 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
  3. 如果广告位支持视频广告,强烈建议在拉取广告前,调用setVideoPlayPolicy设置视频广告的播放策略,有助于提高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()或iad.showAsPopupWindow()视频广告不会有进度条。
    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) {

  }
}

Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇