激励视频广告 Android,腾讯社交联盟广告

激励视频广告

SDK原生渲染是激励视频的接入方式之一。

简介：激励视频广告是指将短视频融入到app场景当中，成为app“任务”之一，用户观看短视频广告后可以得到一些应用内奖励

权限等级：开放

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

分类：激励视频广告样式有横版竖版之分，您可以根据需要创建对应的广告位：

竖版

横版

接入注意事项：

AndroidManifest 文件中需要新增配置

android:name="com.qq.e.ads.PortraitADActivity"

android:screenOrientation="portrait"

android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />

android:name="com.qq.e.ads.LandscapeADActivity"

android:screenOrientation="landscape"

android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />

SDK给开发者的回调(RewardVideoADListener)全部执行在主线程中(异步回调)。

后台会考虑根据广告请求时App横竖屏状态返回相关视频素材，而激励视频广告页面的页面横竖屏设置与展示广告时App当前页面的横竖屏设置保持一致，所以开发者需要尽量保证激励视频广告请求和广告展示两个时刻App的横竖屏状态相同，以让用户获得较好的广告体验。

激励视频广告一次成功拉取的广告数据只允许展示一次。

激励视频广告有过期时间，您可以选择预加载激励视频(提前调用RewardVideoAD的loadAD方法可以实现广告数据和视频素材的预加载)，但是您进行广告展示时务必判断下广告数据是否已经过期，判断方法请参考 GDTUnionDemo 工程

SDK不会持有广告实例(RewardVideoAD)和回调实例(RewardVideoADListener)，所以需要开发者保证广告结束之前广告实例不会被回收掉，以避免回调丢失的情况

主要 API

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

RewardVideoAD

com.qq.e.ads.rewardvideo.RewardVideoAD:

激励视频广告入口，用于初始化广告，加载广告数据并展示广告。

方法名

方法介绍

public RewardVideoAD(final Context context, final String posID, final RewardVideoADListener rewardVideoADListener, final boolean volumeOn)

激励视频广告构造函数，可指定播放时是否有声音；context 是指上下文环境，posID 是广告位 ID，rewardVideoADListener 指定广告状态回调接口，volumeOn为true表示有声播放，false表示静音播放。

public RewardVideoAD(final Context context, final String posID, final RewardVideoADListener rewardVideoADListener)

激励视频广告构造函数，有声播放；参数含义同上

public RewardVideoAD(final Context context, final String appID, final String posID, final RewardVideoADListener rewardVideoADListener)

激励视频广告构造函数，可指定播放时是否有声音；context 是指上下文环境，appID 是媒体 ID，posID 是广告位 ID，rewardVideoADListener 指定广告状态回调接口，volumeOn为true表示有声播放，false表示静音播放。

public RewardVideoAD(final Context context, final String appID, final String posID, final RewardVideoADListener rewardVideoADListener, final boolean volumeOn)

激励视频广告构造函数，有声播放；参数含义同上

loadAD()

加载激励视频广告，加载成功则调用回调RewardVideoADListener.onADLoad()，加载失败则会调用RewardVideoADListener.onError(AdError error)

showAD()

展示激励视频广告，展示成功则调用回调RewardVideoADListener.onADShow()，展示失败则会调用RewardVideoADListener.onError(AdError error)

getECPMLevel()

获取本条广告实时的eCMP价格层级标签，每个层级标签对应线下预定的eCPM价格范围，成功返回一个包含数字的字符串，比如“1”，无权限调用该接口或后台异常会返回空字符串

hasShown()

判断拉取的广告是否已经展示过，一次广告请求只能展示一次。RewardVideoADListener.onADShow()回调成功调用后返回true，其他情况下返回false

checkValidity()

判断拉取的广告是否有效：(1)返回VideoAdValidity#VALID表示有效，可以进行展示；(2)返回VideoAdValidity#OVERDUE表示广告已经过期，不可进行展示；(3)返回VideoAdValidity#SHOWED表示广告已经展示过，不可进行展示；(4)返回VideoAdValidity#NONE_CACHE表示视频资源未缓存，可以进行展示，但是考虑到用户体验，可以等视频缓存之后再进行展示。

getExpireTimestamp()

获取激励视频广告的过期时间，返回值为系统启动后的毫秒数，通过SystemClock.elapsedRealtime()获得。当当前系统启动时间大于过期时间时广告数据失效，不能展示，需要重新拉取广告后再进行展示。RewardVideoADListener.onADLoad()回调调用后返回广告过期时间，其余情况下返回0

getVideoDuration()

获取视频素材时长，单位毫秒

setServerSideVerificationOptions(ServerSideVerificationOptions options)

设置服务端校验需要透穿的参数，服务端校验功能介绍请参照 ServerSideVerificationOptions API 介绍

RewardVideoADListener

com.qq.e.ads.rewardvideo.RewardVideoADListener：

激励视频广告加载、展示整个广告流程的回调,SDK保证所有回调均在主线程中被调用(异步回调)。

方法名

方法介绍

onADLoad()

广告加载成功，可在此回调后进行广告展示，此时广告过期时间确定，可通过RewardVideoAD.getExpireTimestamp()获取

onVideoCached()

视频素材缓存成功，可在此回调后进行广告展示

onADShow()

激励视频广告页面展示，此后RewardVideoAD.hasShown()返回true

onADExpose()

激励视频广告曝光

onReward(Mapmap)

激励视频广告激励发放，若选择了服务端验证，可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id；若未选择服务端验证，则不需关注 map 参数。

onADClick()

激励视频广告被点击

onVideoComplete()

广告视频素材播放完毕

onADClose()

激励视频广告被关闭

onError(AdError error)

广告流程出错，AdError中包含错误码和错误描述

ServerSideVerificationOptions

com.qq.e.ads.rewardvideo.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。

接入代码示例

// 仅展示部分代码，完整代码请参考 Demo 工程

// 1.加载广告，先设置加载上下文环境和条件

// 如果想静音播放，请使用5个参数的构造函数，且volumeOn传false即可

rewardVideoAD = new RewardVideoAD(this, getPosID(), this); // 有声播放

rewardVideoAD.loadAD();

// 2.设置监听器，监听广告状态

/**

* 广告加载成功，可在此回调后进行广告展示

**/

@Override

public void onADLoad() {

adLoaded = true;

String msg = "load ad success ! expireTime = " + new Date(rewardVideoAD.getExpireTimestamp());

Toast.makeText(this, msg, Toast.LENGTH_LONG).show();

}

/**

* 视频素材缓存成功，可在此回调后进行广告展示

*/

@Override

public void onVideoCached() {

videoCached = true;

Log.i(TAG, "onVideoCached");

}

/**

* 激励视频广告页面展示

*/

@Override

public void onADShow() {

Log.i(TAG, "onADShow");

}

/**

* 激励视频广告曝光

*/

@Override

public void onADExpose() {

Log.i(TAG, "onADExpose");

}

/**

* 激励视频触发激励(观看视频大于一定时长或者视频播放完毕)

*

* @param map 若选择了服务端验证，可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id；若未选择服务端验证，则不需关注 map 参数。

*/

@Override

public void onReward(Map map) {

Log.i(TAG, "onReward " + map.get(ServerSideVerificationOptions.TRANS_ID)); // 获取服务端验证的唯一 ID

}

/**

* 激励视频广告被点击

*/

@Override

public void onADClick() {

Log.i(TAG, "onADClick");

}

/**

* 激励视频播放完毕

*/

@Override

public void onVideoComplete() {

Log.i(TAG, "onVideoComplete");

}

/**

* 激励视频广告被关闭

*/

@Override

public void onADClose() {

Log.i(TAG, "onADClose");

}

/**

* 广告流程出错

*/

@Override

public void onError(AdError adError) {

String msg = String.format(Locale.getDefault(), "onError, error code: %d, error msg: %s",

adError.getErrorCode(), adError.getErrorMsg());

Toast.makeText(this, msg, Toast.LENGTH_LONG).show();

}

// 3.展示广告

if (adLoaded) {//广告展示检查1：广告成功加载，此处也可以使用videoCached来实现视频预加载完成后再展示激励视频广告的逻辑

if (!rewardVideoAD.hasShown()) {//广告展示检查2：当前广告数据还没有展示过

long delta = 1000;//建议给广告过期时间加个buffer，单位ms，这里demo采用1000ms的buffer

//广告展示检查3：展示广告前判断广告数据未过期

if (SystemClock.elapsedRealtime() < (rewardVideoAD.getExpireTimestamp() - delta)) {

rewardVideoAD.showAD();

} else {

Toast.makeText(this, "激励视频广告已过期，请再次请求广告后进行广告展示！", Toast.LENGTH_LONG).show();

}

} else {

Toast.makeText(this, "此条广告已经展示过，请再次请求广告后进行广告展示！", Toast.LENGTH_LONG).show();

}

} else {

Toast.makeText(this, "成功加载广告后再进行广告展示！", Toast.LENGTH_LONG).show();

}