Android iOS Unity JS API Media API 常见问题

自渲染

简介

自渲染广告即4.332.1202版本及以前自渲染2.0广告。前文介绍的Banner广告、插屏广告等,app会“收到”一个完整的view对象,开发者无法自定义广告view内部的组件布局(文字TextView、图片ImageView),而自渲染支持开发者自由拼合这些素材,最大程度的满足开发需求;与平台模板相比,自渲染方式更加自由灵活,开发者可以使用其为开发者的应用打造自定义的布局样式

权限等级:开放

前提条件
(1)自渲染广告默认不支持Android API<16 的设备
(2)视频广告的MediaView 内部使用了 TextureView,所以需要在开启硬件加速的窗口中才能使用。当 Android API>=14时,硬件加速默认是开启的

适用场景:平台模板不能满足开发需求,可以使用自渲染

使用自渲染 API拉取到的广告数据主要包含如下字段:

  1. 广告App图标(URL)
  2. 广告媒体图(URL)
  3. 广告标题
  4. 广告描述

除此之外,开发者还可以获取到广告类型,广告星级,广告价格等内容,详见自下文主要API介绍

代码接入示例

自渲染给开发者的回调(NativeADUnifiedListener,NativeADEventListener,NativeADMediaListener)全部执行在主线程中(异步回调)。

public class NativeADUnifiedSampleActivity extends Activity implements NativeADUnifiedListener {

  private NativeUnifiedADData mAdData;
  private NativeUnifiedAD mAdManager;
  private MediaView mMediaView;
  private ImageView mImagePoster;
  private NativeAdContainer mContainer;

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    mAdManager = new NativeUnifiedAD(this, getPosId(), this);


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

    /**
     * 设置本次拉取的视频广告,从用户角度看到的视频播放策略<p/>
     *
     * "用户角度"特指用户看到的情况,并非SDK是否自动播放,与自动播放策略AutoPlayPolicy的取值并非一一对应 <br/>
     *
     * 例如开发者设置了VideoOption.AutoPlayPolicy.NEVER,表示从不自动播放 <br/>
     * 但满足某种条件(如晚上10点)时,开发者调用了startVideo播放视频,这在用户看来仍然是自动播放的
     */
    mAdManager.setVideoPlayPolicy(VideoOption.VideoPlayPolicy.AUTO); // 本次拉回的视频广告,从用户的角度看是自动播放的

    /**
     * 该接口已经废弃,仅支持sdk渲染,不再支持开发者自己渲染 <p/>
     * 当前仅支持VideoADContainerRender.SDK VideoADContainerRender.DEV不再支持
     */
    mAdManager.setVideoADContainerRender(VideoOption.VideoADContainerRender.SDK); // 视频播放前,用户看到的广告容器是由SDK渲染的

    mAdManager.loadData(AD_COUNT);
  }

  ...
  // 广告加载成功回调
  @Override
  public void onADLoaded(List<NativeUnifiedADData> ads) {
    if (ads != null && ads.size() > 0) {
      Message msg = Message.obtain();
      msg.what = MSG_INIT_AD;
      mAdData = ads.get(0);
      msg.obj = mAdData;
      mHandler.sendMessage(msg);
    }
  }

  //加载广告
  private void initAd(final NativeUnifiedADData ad) {
    renderAdUi(ad);

    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(mDownloadButton);
    // 将布局与广告进行绑定
    ad.bindAdToView(this, mContainer, null, clickableViews);
    // 设置广告事件监听
    ad.setNativeAdEventListener(new NativeADEventListener() {
      @Override
      public void onADExposed() {
        Log.d(TAG, "广告曝光");
      }

      @Override
      public void onADClicked() {
        Log.d(TAG, "广告被点击");
      }

      @Override
      public void onADError(AdError error) {
        Log.d(TAG, "错误回调 error code :" + error.getErrorCode()
            + "  error msg: " + error.getErrorMsg());
      }

      @Override
      public void onADStatusChanged() {
        Log.d(TAG, "广告状态变化");
        updateAdAction(mDownloadButton, ad);
      }
    });

    if (ad.getAdPatternType() == AdPatternType.NATIVE_VIDEO) {
      mHandler.sendEmptyMessage(MSG_VIDEO_START);
      // 视频广告需对MediaView进行绑定,MediaView必须为容器mContainer的子View
      ad.bindMediaView(mMediaView, new VideoOption.Builder()
              .setAutoPlayMuted(true).setAutoPlayPolicy(VideoOption.AutoPlayPolicy.WIFI).build(),
          // 视频相关回调
          new NativeADMediaListener() {
            @Override
            public void onVideoInit() {
              Log.d(TAG, "onVideoInit: ");
            }

            @Override
            public void onVideoLoading() {
              Log.d(TAG, "onVideoLoading: ");
            }

            @Override
            public void onVideoReady() {
              Log.d(TAG, "onVideoReady: ");
            }

            @Override
            public void onVideoLoaded(int videoDuration) {
              Log.d(TAG, "onVideoLoaded: ");

            }

            @Override
            public void onVideoStart() {
              Log.d(TAG, "onVideoStart: ");
            }

            @Override
            public void onVideoPause() {
              Log.d(TAG, "onVideoPause: ");
            }

            @Override
            public void onVideoResume() {
              Log.d(TAG, "onVideoResume: ");
            }

            @Override
            public void onVideoCompleted() {
              Log.d(TAG, "onVideoCompleted: ");
            }

            @Override
            public void onVideoError(AdError error) {
              Log.d(TAG, "onVideoError: ");
            }
          });
    }
  }

  @Override
  protected void onResume() {
    super.onResume();
    if (mAdData != null) {
      // 必须要在Actiivty.onResume()时通知到广告数据,以便重置广告恢复状态
      mAdData.resume();
    }
  }
  // 获取广告资源并加载到UI
  private void renderAdUi(NativeUnifiedADData ad) {
    int patternType = ad.getAdPatternType();
    if (patternType == AdPatternType.NATIVE_2IMAGE_2TEXT
        || patternType == AdPatternType.NATIVE_VIDEO) {
      mAQuery.id(R.id.img_logo).image(ad.getIconUrl(), false, true);
      mAQuery.id(R.id.img_poster).image(ad.getImgUrl(), false, true, 0, 0,
          new BitmapAjaxCallback() {
            @Override
            protected void callback(String url, ImageView iv, Bitmap bm, AjaxStatus status) {
              if (iv.getVisibility() == View.VISIBLE) {
                iv.setImageBitmap(bm);
              }
            }
          });
      mAQuery.id(R.id.text_title).text(ad.getTitle());
      mAQuery.id(R.id.text_desc).text(ad.getDesc());
    } else if (patternType == AdPatternType.NATIVE_3IMAGE) {
      mAQuery.id(R.id.img_1).image(ad.getImgList().get(0), false, true);
      mAQuery.id(R.id.img_2).image(ad.getImgList().get(1), false, true);
      mAQuery.id(R.id.img_3).image(ad.getImgList().get(2), false, true);
      mAQuery.id(R.id.native_3img_title).text(ad.getTitle());
      mAQuery.id(R.id.native_3img_desc).text(ad.getDesc());
    }
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    if (mAdData != null) {
      // 必须要在Actiivty.destroy()时通知到广告数据,以便释放内存
      mAdData.destroy();
    }
  }
  // 广告加载失败回调
  @Override
  public void onNoAD(AdError error) {
    Log.d(TAG, "onNoAd error code: " + error.getErrorCode()
        + ", error msg: " + error.getErrorMsg());
  }
  ...
}

主要API

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

NativeUnifiedAD

方法名 方法介绍
public NativeUnifiedAD(final Context context, final String posId, final NativeADUnifiedListener listener) 广告构造函数,其中NativeADUnifiedListener为广告事件回调接口
public NativeUnifiedAD(final Context context, final String appId, final String posId, final NativeADUnifiedListener listener) 广告构造函数,其中NativeADUnifiedListener为广告事件回调接口
loadData(int count) 加载广告,count 指定期望加载的广告数量,根据广告填充情况不同,返回不大于 count 数量的广告
setBrowserType(BrowserType bt) 指定普链广告点击后用于展示落地页的浏览器类型,可选项包括:InnerBrowser(APP 内置浏览器),Sys(系统浏览器),Default(默认,SDK 按照默认逻辑选择
setDownAPPConfirmPolicy(DownAPPConfirmPolicy policy) 指定点击 APP 广告后是否展示二次确认,可选项包括 Default(wifi 不展示,非 wifi 展示),NoConfirm(所有情况不展示)4.330.1200及以后版本支持工信部合规弹窗,在显示工信部弹窗时,该设置无效,工信部弹窗会替换二次确认的弹窗
setCategories(List categories) 测试性接口,不保证有效。传入 app 内类目信息
setMinVideoDuration(int minVideoDuration) 设置返回视频广告的最小视频时长(闭区间,可单独设置),单位:秒 此设置会影响广告填充,请谨慎设置
setMaxVideoDuration(int maxVideoDuration) 设置返回视频广告的最大视频时长(闭区间,可单独设置),单位:秒,合法输入为:5<=maxVideoDuration<=61. 此设置会影响广告填充,请谨慎设置
setVideoPlayPolicy(int policy) 该接口已经废弃
setVideoADContainerRender(int render) 该接口已经废弃

NativeUnifiedADData

方法名 方法介绍
getTitle() 获取广告标题,短文字
getDesc() 获取广告描述,长文字
getIconUrl() 获取 Icon 图片地址
getImgUrl() 获取大图地址
getAdPatternType() 获取广告样式
getImgList() 获取三小图的地址
isAppAd() 判断是否为app广告
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
getAppStatus() 获取应用状态,0:未开始下载;1:已安装;2:需要更新;4:下载中;8:下载完成;16:下载失败;32:下载暂停;64:下载删除
getProgress() 获取app类广告的apk文件下载进度
getDownloadCount() 获取app类广告的下载次数
getAppScore() 获取app类广告的应用评分
getAppPrice() 获取app类广告的应用价格
getVideoDuration() 获取广告的视频时长,广告加载成功即可获取,单位ms。注意:虽然此数值单位为ms,但实际精度为s(向上取整),例如视频真实时长 8100ms ,此处返回9000ms
getPictureWidth() 获取大图素材的宽度
getPictureHeight() 获取大图素材的高度
getVideoCurrentPosition() 获取视频广告当前已播放时长,单位是毫秒
setNativeAdEventListener(NativeADEventListener listener) 设置广告点击曝光等事件监听者
negativeFeedback() 上报广告负反馈信息
preloadVideo(VideoPreloadListener listener) 预加载视频素材,在onVideoCached()回调后展示视频广告不会有加载进度条。
equalsAdData(NativeUnifiedADData adData) 比较两条广告素材(大图小图等字段)是否相同
bindAdToView(Context context, NativeAdContainer container, FrameLayout.LayoutParams adLogoParams, List clickViews) View和广告的绑定,必须设置NativeAdContainer;adlogoParams建议传null,除非一定要改变广告标志相关参数;clickViews为触发广告点击行为的View,必须在container中,不然不会响应点击事件,且开发者不能对clickViews设置OnClickListener,会影响点击事件的上报,点击事件回调可通过NativeADEventListener中onADClicked()回调监听
bindAdToView(Context context, NativeAdContainer container, FrameLayout.LayoutParams adLogoParams, List clickViews, List customClickViews) View和广告的绑定,必须设置NativeAdContainer;adlogoParams建议传null,除非一定要改变广告标志相关参数;clickViews为触发广告点击行为的View,customClickViews点击可以直接下载或进入落地页,两者必须在container中,不然不会响应点击事件,且开发者不能对clickViews和customClickViews设置OnClickListener,会影响点击事件的上报,点击事件回调可通过NativeADEventListener中onADClicked()回调监听
bindMediaView(MediaView view, VideoOption videoOption, NativeADMediaListener mediaListener) 将该条广告数据和视频播放组件MediaView绑定
bindCTAViews(List CTAViews) 绑定响应营销组件(智能电话、外显表单)点击事件的view,注意:开发者不能对CTAViews设置OnClickListener,会影响点击事件的上报;点击事件回调可通过NativeADEventListener中onADClicked()回调监听
getCTAText() 通过该接口可以判断广告是否拥有营销组件能力,返回为空值时表示该广告无法响应营销组件点击事件;返回非空时,表示广告拥有营销组件能力,返回值代表SDK推荐开发者使用的文案,如“立即预约”、“电话咨询”
resume() 当宿主Activity.onResume()时调用,恢复广告状态,如果不调用会导致广告状态错乱
startVideo() 播放视频广告:如果当前未开始则开始播放,如果当前暂停则继续播放,如果当前是停止的则从头播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
pauseVideo() 暂停视频广告的播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
resumeVideo() 继续播放被暂停的视频广告;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
stopVideo() 停止视频广告播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
setVideoMute(boolean mute) 视频广告播放过程中,设置其是否静音,mute为true时表示静音;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
onVideoADExposured(View container) 该接口已经废弃,调用不会有任何效果
destroy() 当开发者不再使用广告,释放View等相关的资源,且广告失效,不能再次使用

VideoOption.Builder

方法名 方法介绍
setAutoPlayPolicy(int policy) 设置视频广告在预览页自动播放的网络条件:VideoOption.AutoPlayPolicy.WIFI表示只在WiFi下自动播放;VideoOption.AutoPlayPolicy.ALWAYS表示始终自动播放,不区分当前网络;VideoOption.AutoPlayPolicy.NEVER表示始终都不自动播放,不区分当前网络,但在WiFi时会预下载视频资源;默认为始终自动播放;模板渲染视频、插屏半屏视频、插屏全屏视频、自渲染视频都可使用
setAutoPlayMuted(boolean mute) 设置视频广告在预览页自动播放时是否静音,默认为true,静音自动播放;模板渲染视频、插屏半屏视频、插屏全屏视频、自渲染视频都可使用
setNeedCoverImage(boolean need) 设置视频广告在预览页未开始播放时是否显示封面图,默认为true,显示封面图;只对自渲染视频广告生效
setNeedProgressBar(boolean need) 设置视频广告在在预览页播放过程中是否显示进度条,默认为true,显示进度条;只对自渲染视频广告生效
setEnableDetailPage(boolean enable) 用户在预览页点击clickableViews或视频区域(setEnableUserControl设置为false)时是否跳转到详情页,默认为true,跳转到详情页;只对自渲染视频广告生效
setEnableUserControl(boolean enable) 设置是否允许用户在预览页点击视频播放器区域控制视频的暂停或播放,默认为false,用户点击时的表现与点击clickableViews一致;如果为true,用户点击时将收到NativeADMediaListener.onVideoClicked回调,而不是NativeADEventListener.onADClicked回调,因为此时并不是广告点击。只对自渲染视频广告生效
setDetailPageMuted(boolean detailPageMuted) 设置视频详情页是否静音播放,默认值为false,即有声播放;模板渲染视频、插屏半屏视频、插屏全屏视频、自渲染视频都可使用

NativeADUnifiedListener

方法名 方法介绍
onADLoaded(List ads) 广告数据获取成功时回调
onNoAD(AdError error) 广告数据获取失败时回调

NativeADEventListener

方法名 方法介绍
onADExposed() 广告被曝光回调
onADClicked() 广告被点击回调
onADError(AdError error) 错误回调
onADStatusChanged() apk数据更新状态时的回调

NativeADMediaListener

方法名 方法介绍
onVideoInit() 视频组件初始化
onVideoLoading() 视频开始加载
onVideoLoaded(int videoDuration) 视频加载完成,videoDuration为视频时长
onVideoReady() 视频组件准备完成
onVideoStart() 视频开始播放
onVideoPause() 视频暂停
onVideoResume() 视频继续播放
onVideoCompleted() 视频播放完成
onVideoStop() 视频播放停止
onVideoClicked() 自渲染视频广告中,如果setEnableUserControl设置为true时,用户点击视频区域时将收到此回调
onVideoError(AdError error) 视频播放报错

接入注意事项

  1. 广告超时:广告从拉取到曝光超过45分钟,将作为无效曝光;广告从拉取到点击超过90分钟,将作为无效点击,不会进行计费。
  2. 包含关系:每一个广告数据NativeUnifiedADData对应一个NativeAdContainer,广告展示元素(图片,视频,按钮)必须在NativeAdContainer之中,如果不在则会造成点击曝光等事件失效。
  3. 可见性:广告根布局NativeAdContainer及其内部元素必须保证其可见性(View是否可见,是否被遮挡,展示面积等),如果不满足可见性,则会导致曝光点击等事件的失效;视频广告则还会重点检查MediaView可见性。
  4. 关于曝光、点击回调和计费方式的说明:不带有视频素材的广告只能曝光一次,点击多次,按照点击计费;带有视频素材的广告可以曝光多次,点击多次,按照曝光计费。
  5. 广告样式:创建自渲染广告位时可以配置支持多种广告样式,渲染广告时需要通过 getAdPatternType() 判断广告样式,返回值对应 AdPatternType类里的常量,可参考 demo 工程里com.qq.e.union.demo.NativeADUnifiedSampleActivity.java
    • 如果返回 NATIVE_2IMAGE_2TEXT,通过 getIconUrl()getImgUrl() 获取图片地址
    • 如果返回 NATIVE_3IMAGE,通过 getImgList() 获取三个小图的地址
    • 如果返回 NATIVE_1IMAGE_2TEXT,通过 getImgUrl() 获取图片地址
    • 如果广告位不支持视频,这里不会出现 NATIVE_VIDEO
  6. 视频广告素材默认是16:9,在开发者调用NativeUnifiedADData.bindMediaView() SDK会动态设置一下MediaView的宽高,保证视频不被拉伸。开发者需要动态调整MediaView时要注意宽高比,防止视频拉伸。
  7. 如果广告位支持视频广告,强烈建议在拉取广告前,调用setVideoPlayPolicy有助于提高eCPM

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