Skip to main content

自渲染广告

创建自渲染广告请求#

NativeAdRequest.Builder builder = new NativeAdRequest.Builder();
builder.setPosId(37059)
.setAdCount(1);

加载自渲染广告#

List<NativeAd> mAds;
NativeAd.load(builder.build(), new NativeAd.NativeAdLoadListener() {
@Override
public void onAdLoadError(int err, String msg) {
//加载失败，err是错误码，msg是描述信息
Log.e(TAG, "err: " + err + " " + msg);
}
@Override
public void onAdLoaded(List<NativeAd> ads) {
//加载成功，参数ads为自渲染广告数组实例
Log.i(TAG, "native ad loaded");
mAds = ads；
}
});

主要API#

com.tencent.klevin.ads.ad.NativeAdRequest.Builder：自渲染广告请求参数构造

com.tencent.klevin.ads.ad.NativeAd：返回的自渲染广告接口

com.tencent.klevin.ads.ad.NativeAd.NativeAdLoadListener：自渲染广告请求回调

请求加载广告说明#

方法名说明参数
Builder.setPosId(long posId)配置自渲染广告的广告位Id【必须】posId为申请的自渲染广告位
Builder.setAdCount(int count)配置广告的拉取个数，默认为1，建议为1，当前可传1或不调用【可选】
Builder.setAutoDownloadPolicy(int policy)配置视频素材的自动下载策略【可选】
ALWAYS(默认)：总是自动下载
WIFI：仅WIFI环境下自动下载
Builder.build()构造自渲染广告的请求参数
NativeAd.load(NativeAdRequest adRequest, NativeAdLoadListener listener)加载自渲染广告adRequest：请求参数NativeAdLoadListener自渲染广告加载回调，加载成功时返回广告数组实例
NativeAd.getECPM()获取ECPM，即千次曝光收益，单位为分。
NativeAd.getPromotedType()返回广告的推广类型：2=下载; 3=网页推广【2.10.1版本新增】
NativeAd.getRequestId()返回广告请求的requestId。【2.11.0版本新增】
NativeAd.getCreativeId()返回广告的创意Id。【2.11.0版本新增】

NativeAdLoadListener回调说明#

方法名说明参数
onAdLoadError(int err, String msg)请求广告失败回调err为相关错误码
msg为相关错误信息
onAdLoaded(List<NativeAd> ads)请求广告成功回调ads为自渲染广告的数组

自渲染广告接口说明#

public abstract class NativeAd {
/**
* 广告内容类型定义，图片
*/
public static final int MEDIA_MODE_IMAGE;
/**
* 广告内容类型定义，视频
*/
public static final int MEDIA_MODE_VIDEO;
/**
* 广告内容类型定义，竖版图片
*/
public static final int MEDIA_MODE_VERTICAL_IMAGE;
/**
* 广告内容类型定义，竖版视频
*/
public static final int MEDIA_MODE_VERTICAL_VIDEO;
/**
* 视频自动播放策略，WiFi下自动播放
*/
public static final int AUTO_PLAY_POLICY_WIFI;
/**
* 视频自动播放策略，总是自动播放，无论什么网络条件
*/
public static final int AUTO_PLAY_POLICY_ALWAYS;
/**
* 视频自动播放策略，从不自动播放，无论什么网络条件
*/
public static final int AUTO_PLAY_POLICY_NEVER;
/**
* 广告请求回调监听
*/
public interface NativeAdLoadListener extends AdLoadListener<List<NativeAd>> {
}
/**
* 返回广告请求的requestId
*/
@Override
public abstract String getRequestId();
/**
* 返回广告的创意Id
*/
@Override
public abstract String getCreativeId();
/**
* 返回广告的推广类型：2=下载; 3=网页推广
*/
public abstract int getPromotedType();
/**
* 游可赢logo，图片宽高比为3.78 : 1
* @return Bitmap对象
*/
public abstract Bitmap getAdLogo();
/**
* 广告图标的加载链接
* @return 图标的url
*/
public abstract String getIcon();
/**
* 广告标题
* @return 字符对象
*/
public abstract String getTitle();
/**
* 广告描述
* @return 字符对象
*/
public abstract String getDescription();
/**
* 广告图片
* @return 图片集合
*/
public abstract List<NativeImage> getImageList();
/**
* 下载按钮的相关文案
* @return 字符对象
*/
public abstract String getDownloadButtonLabel();
/**
* 广告内容类型，图片及视频等，见接口常量定义
* @return 类型常量定义
*/
public abstract int getMediaMode();
/**
* 合规信息五要素，app版本、开发公司、最新更新时间、权限说明url、隐私协议url
* @return 合规信息类ComplianceInfo
*/
public abstract ComplianceInfo getComplianceInfo();
/**
* 广告内容的可视性组件，如图片展示或视频播放，可直接加入到布局中
* @return 广告内容view
*/
public abstract View getAdView();
/**
* 广告内容的宽度，用于展示时的宽高比计算
* @return 内容宽度
*/
public abstract int getAdViewWidth();
/**
* 广告内容的高度，用于展示时的宽高比计算
* @return 内容高度
*/
public abstract int getAdViewHeight();
/**
* 设置是否静音，视频内容可用
* @param isMute 是否静音
*/
public abstract void setMute(boolean isMute);
/**
* 当前是否静音，视频内容可用
* @return 是否静音
*/
public abstract boolean isMute();
/**
* 设置自动播放的策略，需要在广告组件渲染前设置
* @param policy 策略常量定义，传入非法常量则默认为ALWAYS
*/
public abstract void setAutoPlayPolicy(int policy);
/**
* 注册广告可交互view，涉及广告计费，内部处理后会向上回调交互事件
*
* @param contentView 渲染广告最外层的View
* @param downloadViews 点击后触发App下载的view集合
* @param listener 监听回调
*/
public abstract void registerAdInteractionViews(View contentView, List<View> downloadViews,AdInteractionListener listener);
/**
* 注册广告可交互view，涉及广告计费，内部处理后会向上回调交互事件
*
* @param contentView 渲染广告最外层的View
* @param downloadViews 点击后触发App下载的的view集合
* @param detailViews 点击后触发跳转广告详情页的View集合，视频类型广告必须设置
* @param listener 监听回调
*/
public abstract void registerAdInteractionViews(View contentView, List<View> downloadViews,List<View> detailViews, AdInteractionListener listener);
/**
* 注册可触发dislike的view，内部处理后会向上回调点击事件
* @param views 可触发的view集合
* @param listener 监听回调
*/
public abstract void registerAdDislikeViews(List<View> views, AdDislikeListener listener);
/**
* 释放广告相关资源和状态，建议不使用广告时调用
*/
public abstract void destroy();
/**
* 设置视频内容播放相关监听
* @param listener 监听回调
*/
public abstract void setVideoAdListener(VideoAdListener listener);
/**
* 设置apk下载相关监听
* @param listener 监听回调
*/
public abstract void setDownloadListener(AppDownloadListener listener);
/**
* 注册可交互view的相关监听
*/
public interface AdInteractionListener {
/**
* 广告曝光回调
* @param ad 广告对象
*/
void onAdShow(NativeAd ad);
/**
* downloadView点击后的回调
* @param ad 广告对象
* @param view 被点击的view
*/
void onAdClick(NativeAd ad, View view);
/**
* 广告错误回调
* @param ad 广告对象
* @param err 错误码
* @param msg 错误信息
*/
void onAdError(NativeAd ad, int err, String msg);
/**
* detailView点击后的回调
* @param ad 广告对象
* @param view 被点击的view
*/
void onDetailClick(NativeAd ad, View view);
/**
* 广告详情页关闭回调，返回交互类型
* 0.未知 1.广告内webView展示 3.视频详情页
* @param interactionType 交互类型
*/
void onAdDetailClosed(NativeAd ad, int interactionType);
}
/**
* 注册可触发dislike的view的相关监听
*/
public interface AdDislikeListener {
/**
* view点击后的回调
* @param view 被点击的view
*/
void onAdDislike(View view);
}
/**
* 视频内容播放相关监听
*/
public interface VideoAdListener {
/**
* 视频文件下载完成
* @param ad 当前自渲染广告对象
*/
void onVideoCached(NativeAd ad);
/**
* 播放器prepare完成
* @param ad 当前自渲染广告对象
*/
void onVideoLoad(NativeAd ad);
/**
* 播放失败
* @param what 错误码
* @param extra 错误信息
*/
void onVideoError(int what, int extra);
/**
* 播放开始
* @param ad 当前自渲染广告对象
*/
void onVideoStartPlay(NativeAd ad);
/**
* 播放暂停
* @param ad 当前自渲染广告对象
*/
void onVideoPaused(NativeAd ad);
/**
* 播放进度
* @param current 当前进度时间戳(毫秒)
* @param duration 视频总时长(毫秒)
*/
void onProgressUpdate(long current, long duration);
/**
* 播放完成
* @param ad 当前自渲染广告对象
*/
void onVideoComplete(NativeAd ad);
}
}

广告交互行为监听#

这里非常重要！！！注册广告交互行为涉及到广告计费，必须正确设置对应的可交互广告组件。

在加载到信息流广告后，接入方需要注册在广告信息流中可以交互的广告组件，即

NativeAd.registerAdInteractionViews()

方法，以实现广告的功能交互设计，而且调用后不能再对已注册的view设置另外的OnClickListener，否则注册失效。

该方法的参数说明

参数说明
View contentView传入整个需要曝光的广告信息流根布局，不能为空。
List<View> downloadViews可点击交互view的集合，点击注册的view后会触发apk的下载，同时将点击事件回调给接入方。不能为空，否则没有地方触发下载动作，getAdView()返回的广告组件本身可能包含播放暂停的功能，所以点击广告组件不会触发下载。
List<View> detailViews可点击交互view的集合，点击注册的view后会触发跳转视频详情页的动作。视频类型广告必须设置，否则没有地方触发跳转动作，影响转化效果。
AdInteractionListener listener负责向接入方回调广告交互事件，回调说明：onAdShow：通过getAdView()方法返回的广告组件得到有效曝光后会回调该方法，可用于判断广告组件是否正确被曝光onAdClick：上述注册可点击views对应的点击回调onAdError：自渲染广告在加载数据时出现的错误回调

视频播放监听接口#

设置监听视频内容的接口，即

NativeAd.setVideoAdListener()

VideoAdListener的接口说明请见 自渲染广告接口说明 一节。

合规五要素#

获取合规信息类接口，可以获取目标app的版本、开发公司、最新更新时间、权限说明url、隐私协议url。

ComplianceInfo complianceInfo = ad.getComplianceInfo();
String appVersion = complianceInfo.getAppVersion();
String developerName = complianceInfo.getDeveloperName();
String lastUpdateTime = complianceInfo.getLastUpdateTime();
String privacyUrl = complianceInfo.getPrivacyUrl();
String permissionUrl = complianceInfo.getPermissionUrl();

apk下载监听接口#

设置apk下载状态变化的接口，即

NativeAd.setDownloadListener()
private void bindDownloadListener(NativeAd ad) {
ad.setDownloadListener(new AppDownloadListener() {
/**
* 闲置回调（取消下载后恢复初始状态）
*/
@Override
public void onIdle() {
//将下载按钮还原为默认状态
}
/**
* 下载进度回调
* @param totalBytes 下载apk的总字节大小
* @param currBytes 当前下载的字节数
* @param fileName 文件名
* @param appName apk名
*/
@Override
public void onDownloadActive(long totalBytes, long currBytes, String fileName, String appName) {
//更新下载进度条
}
/**
* 下载暂停回调
* @param totalBytes 下载apk的总字节大小
* @param currBytes 当前下载的字节数
* @param fileName 文件名
* @param appName apk名
*/
@Override
public void onDownloadPaused(long totalBytes, long currBytes, String fileName, String appName) {
//更新下载状态为暂停
}
/**
* 下载失败回调
* @param totalBytes 下载apk的总字节大小
* @param currBytes 当前下载的字节数
* @param fileName 文件名
* @param appName apk名
*/
@Override
public void onDownloadFailed(long totalBytes, long currBytes, String fileName, String appName) {
//更新下载状态为失败
}
/**
* 安装完成回调
* @param fileName 文件名
* @param appName apk名
*/
@Override
public void onInstalled(String fileName, String appName) {
//更新状态为安装完成
}
/**
* 下载完成回调
* @param totalBytes 下载apk的总字节大小
* @param fileName 文件名
* @param appName apk名
*/
@Override
public void onDownloadFinished(long totalBytes, String fileName, String appName) {
//更新下载状态为完成
}
});
}

销毁广告对象#

建议在页面销毁时销毁所有的广告对象，或者在确定不再使用广告对象时销毁，销毁时从组件树中移除AdView，防止界面展示异常。

@Override
protected void onDestroy() {
super.onDestroy();
if (mAds != null) {
for (NativeAd ad : mAds) {
ad.destroy();
}
}
mAds = null;
}

接入Dislike服务#

SDK为接入方提供了Dislike逻辑，接入方可以对view进行Dislike事件的注册监听，用户触发不感兴趣的行为(比如关闭广告)后进行反馈，以此优化广告的点击率，提高广告效果及合作伙伴的收益。

在加载到信息流广告后，接入方可以注册在广告信息流中用于关闭广告的View，即

NativeAd.registerAdDislikeViews()

方法，以实现优化反馈，反馈后会将点击事件回调给接入方。同样调用后不能再对已注册的view设置另外的OnClickListener，否则注册失效。

有效曝光条件#

广告组件展示时需要满足一定条件才能视为有效的曝光并纳入计算。

视频类型广告，getAdView()返回的视频组件需要满足以下条件：

  • 组件在屏幕的可见面积达到50%及以上
  • 组件的不透明度在90%及以上

图片类型广告，registerAdInteractionViews()传入的contentView参数组件需要满足以下条件：

  • 组件在屏幕的可见面积达到50%及以上
  • 组件的不透明度在90%及以上

满足以上条件后上报曝光，都会通过AdInteractionListener.onAdShow()回调。