Android iOS Unity JS API Media API 常见问题

模板激励视频广告

简介

权限等级:需申请

前提条件Android SDK 4.270.1140及以上版本才能使用模板激励视频广告,且模板激励视频仅支持Android4.0及以上版本
需要在开发者平台创建模板激励视频广告位,激励视频广告位不会返回广告!!!

简介
模板激励视频广告是指将短视频融入到app场景当中,成为app“任务”之一,用户观看短视频广告后可以得到一些应用内奖励。模板激励视频相比于激励视频会基于优量汇平台模板针对用户提供转化效果更好的播放样式,以提升流量收益。

适用场景
模板激励视频广告是一种常见于游戏内的广告样式,多出现在游戏的复活、登录等位置,或者网服类app的一些增值服务场景。建议开发者在分析媒体属性和功能的基础上,判断是否嵌入模板激励视频广告

分类:模板激励视频广告样式有横版竖版之分,您可以根据播放的场景创建对应屏幕方向的广告位:

竖版 横版

您需要注意以下几点:

  1. SDK给开发者的回调(ExpressRewardVideoAdListener)全部执行在主线程中。
  2. 后台会根据申请广告位时选择的屏幕方向来返回广告,横屏广告位拉取的广告将横屏展示,竖屏广告位拉取的广告将竖屏展示。
  3. 激励视频广告一次成功拉取的广告数据只允许展示一次。
  4. 激励视频广告有过期时间、是否缓存视频,您可以选择预加载激励视频(提前调用 ExpressRewardVideoAD 的 loadAD 方法可以实现广告数据和视频素材的预加载),但是您进行广告展示时务必判断下广告数据是否有效,判断方法请参考 GDTUnionDemo 工程
  5. SDK不会持有广告实例(ExpressRewardVideoAD)和回调实例(ExpressRewardVideoAdListener),所以需要开发者保证广告结束之前广告实例不会被回收掉,以避免回调丢失的情况

接入代码示例

注意:需要在开发者平台创建模板激励视频广告位,激励视频广告位不会返回广告!!!

    // 广告管理者初始化
    mRewardVideoAD = new ExpressRewardVideoAD(this, posId, new ExpressRewardVideoAdListener() {
        @Override
        public void onAdLoaded() {
            mIsLoaded = true;
            Log.i(TAG,
                "onAdLoaded: VideoDuration " + mRewardVideoAD.getVideoDuration() + ", ECPMLevel " +
                    mRewardVideoAD.getECPMLevel());
            showToast("广告拉取成功");
        }

        @Override
        public void onVideoCached() {
            // 在视频缓存完成之后再进行广告展示,以保证用户体验
            mIsCached = true;
            Log.i(TAG, "onVideoCached: ");
        }

        @Override
        public void onShow() {
            Log.i(TAG, "onShow: ");
        }

        @Override
        public void onExpose() {
            Log.i(TAG, "onExpose: ");
        }

        /**
         * 模板激励视频触发激励
         *
         * @param map 若选择了服务端验证,可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id;若未选择服务端验证,则不需关注 map 参数。
         */
        @Override
        public void onReward(Map<String, Object> map) {
            Object o = map.get(ServerSideVerificationOptions.TRANS_ID); // 获取服务端验证的唯一 ID
            Log.i(TAG, "onReward " + o);
        } 

        @Override
        public void onClick() {
            Log.i(TAG, "onClick: ");
        }

        @Override
        public void onVideoComplete() {
            Log.i(TAG, "onVideoComplete: ");
        }

        @Override
        public void onClose() {
            Log.i(TAG, "onClose: ");
        }

        @Override
        public void onError(AdError error) {
            showToast("广告错误: " + error.getErrorMsg());
            Log.i(TAG, "onError: code = " + error.getErrorCode() + " msg = " + error.getErrorMsg());
        }
    });

    // 设置播放时静音状态
    mRewardVideoAD.setVolumeOn(volumeOn);

    // 拉取广告
    mRewardVideoAD.loadAD();

    // 展示广告
    ExpressRewardVideoAD.AdValidity validity = mRewardVideoAD.checkValidity();
        switch (validity) {
          case SHOWED:
            showToast("广告已经展示过!");
            return;
          // 在视频缓存成功后展示,以省去用户的等待时间,提升用户体验
          case NONE_CACHE:
            showToast("广告素材未缓存成功!");
            return;
          case OVERDUE:
            showToast("广告已经过期!");
            return;
          case VALID:
            // 有效广告
            break;
        }
        // 在视频缓存成功后展示,以省去用户的等待时间,提升用户体验
        mRewardVideoAD.showAD(null);

主要 API

ExpressRewardVideoAD

方法名 方法介绍
ExpressRewardVideoAD(Context context, String posId, ExpressRewardVideoAdListener listener) 模板激励视频广告构造函数,context 是指上下文环境,posID 是广告位 listener 指定广告状态回调接口。
ExpressRewardVideoAD(Context context, String appId, String posId, ExpressRewardVideoAdListener listener) 模板激励视频广告构造函数,appId为应用ID,其他参数含义同上
loadAD 拉取模板激励视频广告
showAD(Activity activity) 展示模板激励视频广告,展示成功则调用回调 ExpressRewardVideoAdListener.onShow(),展示失败则会调用 ExpressRewardVideoAdListener.onError(AdError error),如果传入Activity, 则以此实例拉起视频详情页(拉起方式 context.startActivity(intent);),否则以 Application 的 context 启动视频详情页
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
checkValidity() 判断拉取的广告是否有效:(1)返回VideoAdValidity#VALID表示有效,可以进行展示;(2)返回VideoAdValidity#OVERDUE表示广告已经过期,不可进行展示;(3)返回VideoAdValidity#SHOWED表示广告已经展示过,不可进行展示;(4)返回VideoAdValidity#NONE_CACHE表示视频资源未缓存,可以进行展示,但是考虑到用户体验,可以等视频缓存之后再进行展示。
hasShown() 判断拉取的广告是否已经展示过,一次广告请求只能展示一次。RewardVideoADListener.onShow()回调成功调用后返回true,其他情况下返回false
getExpireTimestamp() 获取模板激励视频广告的过期时间,返回值为系统启动后的毫秒数,通过SystemClock.elapsedRealtime()获得。当当前系统启动时间大于过期时间时广告数据失效,不能展示,需要重新拉取广告后再进行展示。 ExpressRewardVideoAdListener.onAdLoaded()回调调用后返回广告过期时间,其余情况下返回0
getVideoDuration() 获取广告播放视频时长
setVolumeOn(boolean volumeOn) 设置是否播放时是否有声播放
setServerSideVerificationOptions(ServerSideVerificationOptions options) 设置服务端校验需要透穿的参数,服务端校验功能介绍请参照 ServerSideVerificationOptions API 介绍

ExpressRewardVideoAdListener

方法名 方法介绍
onAdLoaded() 广告加载成功,可在此回调后进行广告展示,此时广告过期时间确定,可通过 ExpressRewardVideoAD.getExpireTimestamp()获取
onVideoCached() 视频素材缓存成功,可在此回调后进行广告展示
onShow() 模板激励视频广告页面展示,此后 ExpressRewardVideoAD.hasShown()返回true
onExpose() 模板激励视频广告曝光
onReward(Map map) 模板激励视频广告激励发放,若选择了服务端验证,可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id;若未选择服务端验证,则不需关注 map 参数。
onClick() 模板激励视频广告被点击
onVideoComplete() 广告视频素材播放完毕
onClose() 模板激励视频广告被关闭
onError(AdError error) 广告流程出错,AdError中包含错误码和错误描述

ServerSideVerificationOptions

方法名 方法介绍
getCustomData() 获取设置的自定义数据
getUserId() 获取设置的用户 ID
Builder.setCustomData(String customData) 设置自定义数据
Builder.setUserId(String userId) 设置的用户 ID
Builder.build() 生成 ServerSideVerificationOptions 实例

服务端验证说明

当选择需要服务端验证时,开发者需要按照以上接口进行开发,并在开发者平台上填写回调 URL。服务端回调是指在用户看完视频达到奖励条件时,优量汇服务端会向开发者服务端发送一个验证请求,同时客户端会给出 onReward 回调,开发者根据回调进行奖励发放,因为奖励回调和服务端验证请求是同时发送的,开发者后台收到验证请求可能会有延迟或网络原因上的失败,开发者需要平衡用户体验与奖励验证。

服务端回调说明

优量汇服务器会以 GET 方式请求第三方服务的回调链接,并拼接以下参数回传:

pid=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&sig=%s
字段定义 字段名称 字段类型 备注
pid 广告位ID string 签名
appid APP ID string
transid 交易id string 完成观看的唯一交易ID
userid 用户id string 调用SDK透传,应用对用户的唯一标识
extrainfo 其他信息 string 调用SDK传入并透传,如无需要则为空
sig 签名 string 签名

签名生成方式:

sig = sha256(transid:secret)

transid:交易id,secret为您在优量汇媒体平台输入服务端URL时获取到的密钥。

返回约定

返回 json 数据,字段如下:

字段定义 字段名称 字段类型 备注
isValid 校验结果 BOOL 判定结果,是否发放奖励

回调URL格式示例如下:

{ 
   "isValid": true
}

如果回调URL没有正常返回,优量汇后台会重试两次,每次重试间隔200ms。

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