Android iOS Unity JS API Media API 常见问题

自渲染

自渲染是对原有类型的优化和升级,使用自渲染的API,您可以为您的应用打造定制式体验。

简介

即为较旧SDK版本的自渲染2.0广告,开发者可以使用其为开发者的应用打造自定义的布局样式。

权限等级:开放

适用场景:您可自行定义广告布局样式和展示场景

包含内容

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

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

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

主要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() 获取大图地址,使素材展示更完整,优化展示效果,建议通过调用bindImageViews由SDK来渲染图片,详细可参考bindImageViews方法使用说明和Demo实现
getAdPatternType() 获取广告样式
getImgList() 获取三小图的地址,使素材展示更完整,优化展示效果,建议通过调用bindImageViews由SDK来渲染图片,详细可参考bindImageViews方法使用说明和Demo实现
isAppAd() 判断是否为app广告
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
getECPM() 获取本条广告实时的eCPM价格,单位是分;权限提示:调用此接口前,需要向优量汇运营接口人申请实时竞价权限,当无权限调用该接口时,SDK会返回错误码-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()回调监听
bindImageViews(ListimageViews, byte [] defaultImageData) 根据图文广告不同广告类型,将广告数据的图片URL和ImageView绑定并展示,详细参考接入注意事项第5条或Demo实现,支持设置默认图
bindImageViews(ListimageViews, int defaultImageRes) 根据图文广告不同广告类型,将广告数据的图片URL和ImageView绑定并展示,详细参考接入注意事项第5条或Demo实现,支持设置默认图
getCTAText() 通过该接口可以判断广告是否拥有营销组件能力,返回为空值时表示该广告无法响应营销组件点击事件;返回非空时,表示广告拥有营销组件能力,返回值代表SDK推荐开发者使用的文案,如“立即预约”、“电话咨询”
resume() 当宿主Activity.onResume()时调用,恢复广告状态,如果不调用会导致广告状态错乱
startVideo() 播放视频广告:如果当前未开始则开始播放,如果当前暂停则继续播放,如果当前是停止的则从头播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
pauseVideo() 暂停视频广告的播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
resumeVideo() 继续播放被暂停的视频广告;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
stopVideo() 停止视频广告播放;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
setVideoMute(boolean mute) 视频广告播放过程中,设置其是否静音,mute为true时表示静音;该接口只对视频广告预览页有效,在点击视频广告后进入的详情页中调用无效。
onVideoADExposured(View container) 该接口已经废弃,调用不会有任何效果
destroy() 当开发者不再使用广告,释放View等相关的资源,且广告失效,不能再次使用
pauseAppDownload() 暂停下载正在下载中的应用
resumeAppDownload() 继续下载被暂停下载的应用
isWeChatCanvasAd() 是否是微信原生页广告,只有加入白名单的应用支持该类型的广告,如果是该类型广告建议将广告容器中按钮的文案设置为“去微信看看”
getAppMiitInfo() (4.380.1250添加)获取app类广告的app信息,包含应用名称,开发者,版本,apk包大小,隐私政策,权限信息,返回值为NativeUnifiedADAppMiitInfo数据类型,对于非app类广告返回值为null
getButtonText() 返回广告主在广告投放平台设置的按钮文案,如果没设置将返回默认文案:应用下载类广告返回“立即下载”;微信原生页广告返回"去微信看看";其它广告返回“立即查看”

NativeUnifiedADAppMiitInfo(4.380.1250添加)

方法名 方法介绍
getAppName() 应用的名称
getAuthorName() 应用开发者名称
getPackageSizeBytes() 应用apk包的大小,单位byte
getPermissionsUrl() 应用权限信息url,请求该url会得到一个权限信息的json数据,参考自定义下载弹窗的中处理权限的格式
getPrivacyAgreement() 应用隐私政策url,需要使用webview显示该url
getVersionName() 应用版本信息

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数据更新状态时的回调

NativeADEventListenerWithClickInfo (4.333.1203版本新增)

相对NativeADEventListener方法变动 方法介绍
onADClicked(View v) 广告被点击回调,带有点击view的信息
onADClicked() 该函数不会被回调,要使用上面带参数的
其他方法同NativeADEventListener

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()获取图标地址,通过bindImageViews()传入一个ImageView用来展示单个大图
    • 如果返回 NATIVE_3IMAGE,通过bindImageViews()传入三个ImageView用来展示三个小图
    • 如果返回 NATIVE_1IMAGE_2TEXT,通过bindImageViews()传入一个ImageView用来展示单个大图
    • 如果广告位不支持视频,这里不会出现 NATIVE_VIDEO
  6. 视频广告素材默认是16:9,在开发者调用NativeUnifiedADData.bindMediaView() SDK会动态设置一下MediaView的宽高,保证视频不被拉伸。开发者需要动态调整MediaView时要注意宽高比,防止视频拉伸。

代码接入示例

自渲染给开发者的回调(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);
    //加载广告
    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);
    List<ImageView> imageViews = new ArrayList<>();
    if(ad.getAdPatternType() == AdPatternType.NATIVE_2IMAGE_2TEXT ||
        ad.getAdPatternType() == AdPatternType.NATIVE_1IMAGE_2TEXT){
      // 双图双文、单图双文:注册mImagePoster的点击事件
      clickableViews.add(mImagePoster);
      imageViews.add(mImagePoster);
    } else if(ad.getAdPatternType() == AdPatternType.NATIVE_3IMAGE){
      // 三小图广告:注册native_3img_ad_container的点击事件
      clickableViews.add(findViewById(R.id.native_3img_ad_container));
      imageViews.add(findViewById(R.id.img_1));
      imageViews.add(findViewById(R.id.img_2));
      imageViews.add(findViewById(R.id.img_3));
    }
    // 将布局与广告进行绑定
    ad.bindAdToView(this, mContainer, null, clickableViews);
    //图文广告,将要展示图片的ImageView进行绑定
    if (!imageViews.isEmpty()) {
      ad.bindImageViews(imageViews, 0);
    } else 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: ");
            }
          });
    }
    // 设置广告事件监听
    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);
      }
    });
  }

  @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) {
      mImagePoster.setVisibility(View.VISIBLE);
      mAQuery.id(R.id.img_logo).image(ad.getIconUrl(), false, true);
      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.native_3img_title).text(ad.getTitle());
      mAQuery.id(R.id.native_3img_desc).text(ad.getDesc());
    } else if (patternType == AdPatternType.NATIVE_1IMAGE_2TEXT) {
      mAQuery.id(R.id.img_poster).clear();
      mAQuery.id(R.id.text_title).text(ad.getTitle());
      mAQuery.id(R.id.text_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());
  }
  ...
}

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