腾讯社交联盟广告

Android iOS Unity JS API Media API 常见问题

平台模板

简介

权限等级:开放

平台模板广告:即4.332.1202版本及以前的原生模板广告

前提要求Android SDK 4.10.547及以上版本

适用场景:如果我们提供的模板广告样式符合您的需求,建议直接使用该接口

分类
平台模板有七种广告样式可选:

上图下文
(图片尺寸1280×720)
上文下图
(图片尺寸1280×720)
左图右文
(图片尺寸1200×800)
左文右图
(图片尺寸1200×800)
双图双文
(大图尺寸1280×720)
纯图片
(图片尺寸800×1200)
纯图片
(图片尺寸1280×720)

注意:接入代码和 API 均只适用于平台模板广告位。误用其他广告位 ID 使用平台模板广告的接口,则会导致无广告返回。

接入代码示例

  // 仅展示部分代码,完整代码请参考 GDTUnionDemo 工程
  // 1.加载广告,先设置加载上下文环境和条件
  private void refreshAd() {
    nativeExpressAD = new NativeExpressAD(this, new ADSize(340, ADSize.AUTO_HEIGHT), Constants.NativeExpressPosID, this); // 传入Activity
    // 注意:如果您在平台上新建平台模板广告位时,选择了支持视频,那么可以进行个性化设置(可选)
    nativeExpressAD.setVideoOption(new VideoOption.Builder()
      .setAutoPlayPolicy(VideoOption.AutoPlayPolicy.WIFI) // WIFI 环境下可以自动播放视频
      .setAutoPlayMuted(true) // 自动播放时为静音
      .build()); //

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

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

    nativeExpressAD.loadAD(1);
  }

  // 2.设置监听器,监听广告状态
  @Override
  public void onNoAD(AdError error) {
    Log.i("AD_DEMO", String.format("onADError, error code: %d, error msg: %s", error.getErrorCode(), error.getErrorMsg()));
  }

  @Override
  public void onADLoaded(List<NativeExpressADView> adList) {
    Log.i(TAG, "onADLoaded: " + adList.size());
    // 释放前一个 NativeExpressADView 的资源
    if (nativeExpressADView != null) {
      nativeExpressADView.destroy();
    }
    // 3.返回数据后,SDK 会返回可以用于展示 NativeExpressADView 列表
    nativeExpressADView = adList.get(0);
    if (nativeExpressADView.getBoundData().getAdPatternType() == AdPatternType.NATIVE_VIDEO) {
      nativeExpressADView.setMediaListener(mediaListener);
    }
    nativeExpressADView.render();
    if (container.getChildCount() > 0) {
      container.removeAllViews();
    }

    // 需要保证 View 被绘制的时候是可见的,否则将无法产生曝光和收益。
    container.addView(nativeExpressADView);
  }

  @Override
  public void onRenderFail(NativeExpressADView adView) {
    Log.i(TAG, "onRenderFail");
  }

  @Override
  public void onRenderSuccess(NativeExpressADView adView) {
    Log.i(TAG, "onRenderSuccess");
  }

  @Override
  public void onADExposure(NativeExpressADView adView) {
    Log.i(TAG, "onADExposure");
  }

  @Override
  public void onADClicked(NativeExpressADView adView) {
    Log.i(TAG, "onADClicked");
  }

  @Override
  public void onADClosed(NativeExpressADView adView) {
    Log.i(TAG, "onADClosed");
  }

  @Override
  public void onADLeftApplication(NativeExpressADView adView) {
    Log.i(TAG, "onADLeftApplication");
  }

  @Override
  public void onADOpenOverlay(NativeExpressADView adView) {
    Log.i(TAG, "onADOpenOverlay");
  }

  @Override
  public void onADCloseOverlay(NativeExpressADView adView) {
    Log.i(TAG, "onADCloseOverlay");
 }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // 4.使用完了每一个 NativeExpressADView 之后都要释放掉资源
    if (nativeExpressADView != null) {
      nativeExpressADView.destroy();
    }
  }

private NativeExpressMediaListener mediaListener = new NativeExpressMediaListener() {
@Override
public void onVideoInit(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoInit: "
      + getVideoInfo(nativeExpressADView.getBoundData().getProperty(AdData.VideoPlayer.class)));
}

@Override
public void onVideoLoading(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoLoading");
}

@Override
public void onVideoReady(NativeExpressADView nativeExpressADView, long l) {
  Log.i(TAG, "onVideoReady");
}

@Override
public void onVideoStart(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoStart: "
      + getVideoInfo(nativeExpressADView.getBoundData().getProperty(AdData.VideoPlayer.class)));
}

@Override
public void onVideoPause(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoPause: "
      + getVideoInfo(nativeExpressADView.getBoundData().getProperty(AdData.VideoPlayer.class)));
}

@Override
public void onVideoComplete(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoComplete: "
      + getVideoInfo(nativeExpressADView.getBoundData().getProperty(AdData.VideoPlayer.class)));
}

@Override
public void onVideoError(NativeExpressADView nativeExpressADView, AdError adError) {
  Log.i(TAG, "onVideoError");
}

@Override
public void onVideoPageOpen(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoPageOpen");
}

@Override
public void onVideoPageClose(NativeExpressADView nativeExpressADView) {
  Log.i(TAG, "onVideoPageClose");
}
};   

主要 API

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

NativeExpressAD

方法名 方法介绍
NativeExpressAD(final Context context, final ADSize adSize, final String posID, final NativeExpressADListener listener) 平台模板广告构造函数,context 是指上下文环境,这里必须传入开发者的 Activity,adSize 是指定广告 View 的宽高,posID 是广告位 ID,listener 指定广告状态回调接口。
关于 adSize 参数的说明:
1.如果开发者需要自己设置 adSize 的值,那么宽度、高度都必须是大于0的整数,单位为 dp;
2.如果开发者将 adSize 的高度设为 SDK 提供的 ADSize.AUTO_HEIGHT,可以不需要自己调整广告的高度,此时只需要开发者设定广告的宽度,SDK 会自动判断出广告在这个宽度下的最佳高度,并将 NativeExpressADView 的高度设置为最佳高度。高度方面,我们建议尽量使用 AUTO_HEIGHT,保证广告的展示效果;
3. 如果开发者将广告的宽度设为 SDK 提供的 ADSize.FULL_WIDTH,NativeExpressADView 会最大程度的使用其父控件给予的宽度,此时开发者可以自己设置高度或者选用 AUTO_HEIGHT。
NativeExpressAD(final Context context, final ADSize adSize, final String appID, final String posID, final NativeExpressADListener listener) 平台模板广告构造函数,context 是指上下文环境,这里必须传入开发者的 Activity,adSize 是指定广告 View 的宽高,appId 是媒体ID,posID 是广告位 ID,listener 指定广告状态回调接口。
关于 adSize 参数的说明:
1.如果开发者需要自己设置 adSize 的值,那么宽度、高度都必须是大于0的整数,单位为 dp;
2.如果开发者将 adSize 的高度设为 SDK 提供的 ADSize.AUTO_HEIGHT,可以不需要自己调整广告的高度,此时只需要开发者设定广告的宽度,SDK 会自动判断出广告在这个宽度下的最佳高度,并将 NativeExpressADView 的高度设置为最佳高度。高度方面,我们建议尽量使用 AUTO_HEIGHT,保证广告的展示效果;
3. 如果开发者将广告的宽度设为 SDK 提供的 ADSize.FULL_WIDTH,NativeExpressADView 会最大程度的使用其父控件给予的宽度,此时开发者可以自己设置高度或者选用 AUTO_HEIGHT。
loadAD(int count) 加载广告,count 指定期望加载的广告数量,根据广告填充情况不同,返回不大于 count 数量的广告
setBrowserType(BrowserType bt) 指定普链广告点击后用于展示落地页的浏览器类型,可选项包括:InnerBrowser(APP 内置浏览器),Sys(系统浏览器),Default(默认,SDK 按照默认逻辑选择
setDownAPPConfirmPolicy(DownAPPConfirmPolicy policy) 指定点击 APP 广告后是否展示二次确认,可选项包括 Default(wifi 不展示,非wifi 展示),NoConfirm(所有情况不展示)4.330.1200及以后版本支持工信部合规弹窗,在显示工信部弹窗时,该设置无效,工信部弹窗会替换二次确认的弹窗
setVideoOption(VideoOption videoOption) (可选方法)指定视频广告的播放配置,配置包含:
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. 此设置会影响广告填充,请谨慎设置
setVideoPlayPolicy(int policy) 设置本次拉取的视频广告,从用户角度看到的视频播放策略;可选项包括自VideoOption.VideoPlayPolicy.AUTO(在用户看来,视频广告是自动播放的)和VideoOption.VideoPlayPolicy.MANUAL(在用户看来,视频广告是手动播放的);如果广告位支持视频,强烈建议调用此接口设置视频广告的播放策略,有助于提高eCPM值;如果广告位不支持视频,忽略本接口

NativeExpressADListener

方法名 方法介绍
onNoAD(AdError error) 无广告填充
onADLoaded(List adList) 广告数据加载成功,返回了可以用来展示广告的 NativeExpressADView,但是想让广告曝光还需要调用 NativeExpressADView 的 render 方法
onRenderFail(NativeExpressADView adView) NativeExpressADView 渲染广告失败
onRenderSuccess(NativeExpressADView adView) NativeExpressADView 渲染广告成功
onADExposure(NativeExpressADView adView) 广告曝光
onADClicked(NativeExpressADView adView) 广告点击
onADClosed(NativeExpressADView adView) 广告被关闭,将不再显示广告,此时广告对象已经释放资源,不可以再次用来展示了
onADLeftApplication(NativeExpressADView adView) 因为广告点击等原因离开当前 app 时调用
onADOpenOverlay(NativeExpressADView adView) 广告展开遮盖时调用
onADCloseOverlay(NativeExpressADView adView) 广告关闭遮盖时调用

NativeExpressMediaListener

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

NativeExpressADView

方法名 方法介绍
render() 渲染广告,渲染结果会在 NativeExpressAD.NativeExpressADListener 回调,如果不调用这个方法,NativeExpressADView 就不会把广告图片等资源加载进来,也不会产生曝光等收益
setAdSize(ADSize adSize) 改变 NativeExpressADView 的尺寸,ADSize 指定了广告 View 的宽高,因此必须大于0,单位是 dp。
注意:
SDK 可能在后续版本中废弃这个方法,我们推荐开发者在 NativeExpressAD 构造方法中,给 adSize 的宽度手动指定一个自己需要的宽度或者设为 ADSize.FULL_WIDTH,给 adSize 的高度时设置 ADSize.AUTO_HEIGHT,来保证广告展示的效果。
destroy() 释放 NativeExpressADView 占用的资源,当不再展示广告时一定要调用这个方法去释放资源
setMediaListener(NativeExpressMediaListener mediaListener) 设置监听器,监听视频广告的状态变化
preloadVideo() 预加载视频,加载完成后会回调NativeExpressMediaListener的onVideoCached()方法
AdData getBoundData() 获取广告 View 绑定的广告数据,如广告信息、播放进度等

AdData

方法名 方法介绍
getTitle() 标题
getDesc() 描述
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
getAdPatternType() 获取广告样式,目前只支持 AdPatternType.NATIVE_VIDEO
getProperty(String property) 广告其他属性,保留接口,目前无返回值
getProperty(Class type) 如果是视频广告,可通过该接口传入 AdData.VideoPlayer.class 获取播放器实例,需要注意的是仅当视频回调 onVideoInit 被调用后才会有实例返回
equalsAdData(AdData adData) 是否为同一广告对象
getVideoDuration() 获取广告的视频时长,广告加载成功即可获取,单位ms。注意:虽然此数值单位为ms,但实际精度为s(向上取整),例如视频真实时长 8100ms ,此处返回9000ms

VideoPlayer

方法名 方法介绍
getVideoState() 返回播放器当前状态,0:播放出错,1:初始状态,2:准备播放状态,3:播放状态,4:停止状态,5:暂停状态,6:完成状态
getDuration() 当视频素材 ready 后,获取总时长,单位 ms
getCurrentPosition() 当视频正在播放时,获取当前播放的位置,单位 ms

接入注意事项

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

  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.
腾讯公司 版权所有 | 加入优量汇