原生模版广告

创建原生模版广告请求#

NativeExpressAdRequest.Builder builder = new NativeExpressAdRequest.Builder();
builder.setPosId(37569)
        .setAdCount(1);
builder.setMute(true);

加载原生模版广告#

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

主要API#

com.tencent.klevin.ads.ad.NativeExpressAdRequest.Builder：原生模版广告请求参数构造
com.tencent.klevin.ads.ad.NativeExpressAd：返回的原生模版广告接口
com.tencent.klevin.ads.ad.NativeExpressAd.NativeExpressAdLoadListener：原生模版广告请求回调

请求加载广告说明

方法名	说明	参数
Builder.setPosId(long posId)	配置原生模版广告的广告位Id	【必须】posId为申请的原生广告位
Builder.setAdCount(int count)	配置广告的拉取个数，默认为1，建议为1，当前可传1或不调用	【可选】
Builder.setMute(boolean mute)	配置自动播放时是否静音
Builder.build()	构造原生模版广告的请求参数
NativeExpressAd.load(NativeExpressAdRequest adRequest, NativeExpressAdLoadListener listener)	加载原生模版广告	adRequest：请求参数；NativeAdLoadListener原生模版广告加载回调，加载成功时返回广告数组实例
NativeExpressAd.getECPM()	获取ECPM，即千次曝光收益，单位为分。
NativeExpressAd.getPromotedType()	返回广告的推广类型：2=下载; 3=网页推广【2.10.1版本新增】
NativeExpressAd.getRequestId()	返回广告请求的requestId。【2.11.0版本新增】
NativeExpressAd.getCreativeId()	返回广告的创意Id。【2.11.0版本新增】

NativeExpressAdLoadListener回调说明

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

原生模版广告接口说明#

public abstract class NativeExpressAd {
    /**
     * 视频自动播放策略，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 NativeExpressAdLoadListener extends AdLoadListener<List<NativeExpressAd>> {
    }
    /**
     * 返回广告请求的requestId
     */
    @Override
    public abstract String getRequestId();

    /**
     * 返回广告的创意Id
     */
    @Override
    public abstract String getCreativeId();
    /**
     * 返回广告的推广类型：2=下载; 3=网页推广
     */
    public abstract int getPromotedType();
    /**
     * 广告内容的可视化组件，可直接加入到布局中
     *
     * @return
     */
    public abstract View getAdView();
    /**
     * 是否为视频广告
     *
     * @return 是否为视频广告
     */
    public abstract boolean isVideoAd();
    /**
     * 设置自动播放的策略，需要在广告组件渲染前设置
     *
     * @param policy 策略常量定义，传入非法常量则默认为ALWAYS
     */
    public abstract void setAutoPlayPolicy(int policy);
    /**
     * 设置广告尺寸
     *
     * @param adSize
     */
    public abstract void setAdSize(AdSize adSize);
    /**
     * 设置广告交互事件监听
     *
     * @param listener
     */
    public abstract void setInteractionListener(AdInteractionListener listener);
    /**
     * 设置apk下载相关监听
     *
     * @param listener
     */
    public abstract void setDownloadListener(AppDownloadListener listener);
    /**
     * 设置视频内容播放相关监听
     *
     * @param listener
     */
    public abstract void setVideoAdListener(VideoAdListener listener);

    /**
     * 渲染广告
     */
    public abstract void render();
    /**
     * 释放广告相关资源和状态，建议不使用广告时调用
     */
    public abstract void destroy();
    /**
     * 注册可交互view的相关监听
     */
    public interface AdInteractionListener {
        /**
         * 广告渲染完成回调
         *
         * @param adView 模版广告View
         * @param width 模版广告View的宽度（单位：dp）
         * @param height 模版广告View的高度（单位：dp）
         */
        void onRenderSuccess(View adView, float width, float height);
        /**
         * 广告渲染失败回调
         *
         * @param adView 模版广告View
         * @param error 错误码
         * @param msg 错误消息
         */
        void onRenderFailed(View adView, int error, String msg);
        /**
         * 广告曝光回调
         *
         * @param adView 模版广告View
         */
        void onAdShow(View adView);
        /**
         * view点击后的回调
         *
         * @param adView 模版广告View
         */
        void onAdClick(View adView);
        /**
         * 广告关闭
         * @param adView 模版广告View
         */
        void onAdClose(View adView);
        /**
         * 广告详情页关闭回调，返回交互类型
         * 0.未知 1.广告内webView展示 3.视频详情页
         * @param interactionType 交互类型
         */
        void onAdDetailClosed(int interactionType);
    }

    /**
     * 视频内容播放相关监听
     */
    public interface VideoAdListener {
        /**
         * 视频文件下载完成
         *
         * @param adView 模版广告View
         */
        void onVideoCached(View adView);
        /**
         * 播放器prepare完成
         *
         * @param adView 模版广告View
         */
        void onVideoLoad(View adView);
        /**
         * 播放失败
         *
         * @param adView 模版广告View
         * @param what  错误码
         * @param extra 错误信息
         */
        void onVideoError(View adView, int what, int extra);
        /**
         * 播放开始
         *
         * @param adView 模版广告View
         */
        void onVideoStartPlay(View adView);
        /**
         * 播放暂停
         *
         * @param adView 模版广告View
         */
        void onVideoPaused(View adView);
        /**
         * 播放进度
         *
         * @param adView 模版广告View
         * @param current  当前进度时间戳(毫秒)
         * @param duration 视频总时长(毫秒)
         */
        void onProgressUpdate(View adView, long current, long duration);
        /**
         * 播放完成
         *
         * @param adView 模版广告View
         */
        void onVideoComplete(View adView);
    }
}

展示原生模版广告#

这里非常重要！！！原生模版广告必须先渲染才能进行展示

展示原生模版广告前，需要先设置广告监听NativeExpressAd.setInteractionListener()，之后调用NativeExpressAd.render()进行广告渲染，当收到渲染成功回调onRenderSuccess后才可以进行广告展示。

mAd.setInteractionListener(new NativeExpressAd.AdInteractionListener() {
    @Override
    public void onRenderSuccess(View adView, float width, float height) {
        Log.d(TAG, "onRenderSuccess, width: " + width + ", height: " + height);
        mAdContainer.removeAllViews();
        mAdContainer.addView(adView);
    }
    @Override
    public void onRenderFailed(View adView, int error, String msg) {
        Log.d(TAG, "onRenderFailed, err: " + error + ", msg: " + msg);
    }
    @Override
    public void onAdShow(View adView) {
        Log.d(TAG, "onAdShow");
    }
    @Override
    public void onAdClick(View adView) {
        Log.d(TAG, "onAdClick");
    }
    @Override
    public void onAdClose(View adView) {
        Log.d(TAG, "onAdClose");
    }
    @Override
    public void onAdDetailClosed(int interactionType) {
        Log.d(TAG, "onAdDetailClosed, interactionType : " + interactionType);
    }
  });

  // 渲染模版广告!!!非常重要
  mAd.render();

广告交互行为监听#

在渲染原生模版广告前，需要先设置广告交互监听。

AdInteractionListener listener参数

负责向接入方回调广告交互事件，回调说明：

onRenderSuccess：原生模版广告View渲染成功后会回调该方法，之后可把模版View添加在布局中进行显示
onRenderFailed：原生模版广告View渲染失败时出现的错误回调
onAdShow：原生模版广告的广告组件得到有效曝光后会回调该方法，可用于判断广告组件是否正确被曝光
onAdClick：广告组件被点击时回调该方法
onAdClose：广告组件点击了关闭时回调该方法
onAdDetailClosed：广告详情页关闭时回调该方法

视频播放监听接口#

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

NativeExpressAd.setVideoAdListener()

VideoAdListener的接口说明请见原生模版广告接口说明一节。

apk下载监听接口#

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

NativeExpressAd.setDownloadListener()

private void bindDownloadListener(NativeExpressAd ad) {
    ad.setDownloadListener(new AppDownloadListener() {
        /**
         * 闲置回调（取消下载后恢复初始状态）
         */
        @Override
        public void onIdle() {
            // 下载闲置状态
        }
        /**
         * 下载开始回调
         * @param totalBytes 下载apk的总字节大小
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onDownloadStart(long totalBytes, String fileName, String appName) {
            Log.d(TAG, "download start, app: " + appName);
        }
        /**
         * 下载进度回调
         * @param totalBytes 下载apk的总字节大小
         * @param currBytes 当前下载的字节数
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onDownloadActive(long totalBytes, long currBytes, String fileName, String appName) {
            int progress = 0;
            if (totalBytes <= 0L) {
                progress = 0;
            } else {
                progress = (int) (currBytes * 100 / totalBytes);
            }
            Log.d(TAG, "download progress " + progress + "%" + ", app: " + appName);
        }
        /**
         * 下载暂停回调
         * @param totalBytes 下载apk的总字节大小
         * @param currBytes 当前下载的字节数
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onDownloadPaused(long totalBytes, long currBytes, String fileName, String appName) {
            Log.d(TAG, "download paused, app: " + appName);
        }
        /**
         * 下载失败回调
         * @param totalBytes 下载apk的总字节大小
         * @param currBytes 当前下载的字节数
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onDownloadFailed(long totalBytes, long currBytes, String fileName, String appName) {
            Log.d(TAG, "download failed, app: " + appName);
        }
        /**
         * 下载完成回调
         * @param totalBytes 下载apk的总字节大小
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onDownloadFinished(long totalBytes, String fileName, String appName) {
            Log.d(TAG, "download finished, app: " + appName);
        }
        /**
         * 安装完成回调
         * @param fileName 文件名
         * @param appName app名
         */
        @Override
        public void onInstalled(String fileName, String appName) {
            Log.d(TAG, "app installed, app: " + appName);
        }
    });
}

销毁广告对象#

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

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

有效曝光条件#

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

视频类型广告，onRenderSuccess返回的模版广告View组件需要满足以下条件：

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

图片类型广告，onRenderSuccess返回的模版广告View组件需要满足以下条件：

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

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