Android iOS Unity JS API Media API 常见问题

插屏半屏广告

简介

权限等级:开放

插屏半屏广告接入需要在开发者平台创建插屏广告,可选择横版插屏和横/竖版插屏。

插屏半屏广告分为小规格图文(弹窗)、小规格纯图片(弹窗)和大规格纯图片(竖屏)、插屏横屏视频、插屏竖屏视频:

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

您需要注意以下几点:

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

主要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”,无权限调用该接口或后台异常会返回空字符串
isValid() 广告是否有效,无效广告将无法展示
close() 关闭插屏半屏广告
destroy() 当不需要插屏半屏广告实例时调用此方法来主动释放资源

UnifiedInterstitialADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息
onADReceive() 插屏半屏广告加载完毕,此回调后才可以调用 show 方法
onVideoCached() 插屏半屏视频广告,视频素材下载完成
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 对象包含了错误码和错误信息,错误码的详细内容可以参考右侧快捷导航中的「错误码」
onVideoPageOpen() 进入视频落地页
onVideoPageClose() 退出视频落地页

代码接入示例

详细内容请参考压缩包中的代码示例

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);
    }
    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, "广告加载成功 ! ", Toast.LENGTH_LONG).show();
    // onADReceive之后才能调用getAdPatternType()
    if(iad.getAdPatternType() == AdPatternType.NATIVE_VIDEO){
      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 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. 您可以按需进行视频广告播放的个性化配置。
  2. 您需要将 GDTUnionDemo 工程中的 /res/drawable/hdpi//res/drawable/xxhdpi/ 文件夹里面的以 gdt_ic_express_* 开头的文件拷贝到自己的工程目录下,且不可以修改文件名字,这些图标是视频播放器里面的按钮图标,需要注意 gradle 开启 shrinkresource 后,这些图片资源可能会被优化删除。
  3. 您需要处理好 Activity 的运行时变更,由于视频广告可以跟随手机屏幕的方向旋转和全屏播放,请处理好 Activity 的运行时变更(最简单的方式就是在 AndroidManifest 文件中给您的 Activity 加上 android:configChanges="keyboard|keyboardHidden|orientation|screenSize" 属性),不要让播放视频广告的 Activity 被销毁重建,具体代码可以参考 GDTUnionDemo。
  4. 如果广告位支持视频广告,强烈建议在拉取广告前,调用setVideoPlayPolicy设置视频广告的播放策略,有助于提高eCPM

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