Help Center/Details/

激励视频

简介

激励视频广告需要让用户主动选择去观看,广告的效果为观看完毕视频广告,发放奖励给用户。

使用场景包括但不限于
1、游戏等应用内观看视频广告获得游戏内金币等;
2、积分类应用接入;

支持的广告尺寸: 全屏横屏(宽高比16:9)、全屏竖屏(宽高比9:16)。Android端暂不支持重力旋转

权限

模板渲染激励视频广告: 默认提供
SDK渲染激励视频广告: 已回收,不再提供创建

请求方法

备注:模板渲染激励视频和SDK渲染激励视频的广告请求方式上没有差异,仅是请求参数上的差异。
模板渲染的激励视频请求方法中需要设置setExpressViewAcceptedSize参数 设置的值大于0即可

创建TTAdNative对象

TTAdNative mTTAdNative=TTAdSdk.getAdManager().createAdNative(this);

模版渲染请求AdSlot

AdSlot adSlot = new AdSlot.Builder()
        .setCodeId(codeId)
        .setRewardName("金币") //奖励的名称 选填
        .setRewardAmount(3)  //奖励的数量 选填
        //模板广告需要设置期望个性化模板广告的大小,单位dp,激励视频场景,只要设置的值大于0即可
        且仅是模板渲染的代码位ID使用,非模板渲染代码位切勿使用
        .setExpressViewAcceptedSize(500,500)
        .setUserID("tag123")//tag_id
        .setMediaExtra("media_extra") //附加参数
        .setOrientation(orientation) //必填参数,期望视频的播放方向:TTAdConstant.HORIZONTAL 或 TTAdConstant.VERTICAL
        .setAdLoadType(PRELOAD)//推荐使用,用于标注此次的广告请求用途为预加载(当做缓存)还是实时加载,方便后续为开发者优化相关策略
        .build();

SDK渲染请求AdSlot

AdSlot adSlot = new AdSlot.Builder()
        .setCodeId(codeId)
        .setRewardName("金币") //奖励的名称 选填
        .setRewardAmount(3)  //奖励的数量 选填
        .setUserID("tag123")//tag_id
        .setMediaExtra("media_extra") //附加参数
        .setOrientation(orientation) //必填参数,期望视频的播放方向:TTAdConstant.HORIZONTAL 或 TTAdConstant.VERTICAL
        .setAdLoadType(PRELOAD)//推荐使用,用于标注此次的广告请求用途为预加载(当做缓存)还是实时加载,方便后续为开发者优化相关策略
        .build();

参数说明

方法 说明
setCodeId() 平台创建的代码位ID 以9开头9位数字
setRewardName() 奖励名称(选填) 与创建代码位填写的保持一致 。3300及以上版本中废弃
setRewardAmount() 奖励数量(选填) 与创建代码位填写的保持一致。3300及以上版本中废弃
setExpressViewAcceptedSize() 设置请求模板广告素材的尺寸 单位:dp , 设置的值大于0即可(模板广告必填)
setUserID() tag_id
setMediaExtra() 用户透传信息(选填)仅支持单个json对象格式,不可以嵌套json对象
setOrientation() 期望视频的播放方向 与创建代码位勾选的方向保持一致 (必填)
setAdLoadType() 用于标注此次的广告请求用途为预加载(当做缓存)还是实时加载,方便后续为开发者优化相关策略,传入参数值:
UNKNOWN//未知,默认值,开发者未传入,或当此次加载的广告用途未知时使用
PRELOAD//预加载,当此次加载的广告用途为预加载(当作缓存)时使用
LOAD//实时加载,当此次加载的广告用途为实时播放时使用

注:模板渲染代码位setExpressViewAcceptedSize必填 ,SDK模板渲染代码位ID勿传

请求广告

调用TTAdNative.loadRewardVideoAd(AdSlot var1, @NonNull TTAdNative.RewardVideoAdListener var2)异步加载激励视频广告

mTTAdNative.loadRewardVideoAd(adSlot, new TTAdNative.RewardVideoAdListener() {
            @Override
            public void onError(int code, String message) {
                Log.e(TAG, "Callback --> onError: " + code + ", " + String.valueOf(message));
                TToast.show(RewardVideoActivity.this, message);

            }

            //视频广告加载后,视频资源缓存到本地的回调,在此回调后,播放本地视频,流畅不阻塞。
            @Override
            public void onRewardVideoCached() {
                Log.e(TAG, "Callback --> onRewardVideoCached");
                mIsLoaded = true;
                TToast.show(RewardVideoActivity.this, "Callback --> rewardVideoAd video cached");
            }

            @Override
            public void onRewardVideoCached(TTRewardVideoAd ad) {
                Log.e(TAG, "Callback --> onRewardVideoCached");
                mIsLoaded = true;
                TToast.show(RewardVideoActivity.this, "Callback --> rewardVideoAd video cached");
                ad.showRewardVideoAd(RewardVideoActivity.this, TTAdConstant.RitScenes.CUSTOMIZE_SCENES, "scenes_test");

            }

TTRewardVideoAd

方法 参数 说明
void setRewardAdInteractionListener(TTRewardVideoAd.RewardAdInteractionListener var1) TTRewardVideoAd.RewardAdInteractionListener var1 方法说明:注册激励视频广告回调
参数说明:listener 交互监听器
void setRewardPlayAgainInteractionListener(TTRewardVideoAd.RewardAdInteractionListener var1) TTRewardVideoAd.RewardAdInteractionListener var1 方法说明:注册激励视频再看一个广告回调
参数说明: listener 交互监听器
void setDownloadListener(TTAppDownloadListener var1) TTAppDownloadListener var1 方法说明:注册广告的下载回调
参数说明:listener 下载状态回调
int getInteractionType() 方法说明:
- 2在浏览器内打开 (普通类型
-3落地页(普通类型)
- 4:应用下载,
- 5:拨打电话
-1 未知类型
参数说明:无
@MainThreadvoid showRewardVideoAd(Activity var1) Activity var1 方法说明:展示激励视频广告接口
参数说明:宿主activity
Map<String, Object> getMediaExtraInfo() 方法说明:返回广告额外信息
参数说明:无
void showRewardVideoAd(Activity var1, RitScenes var2, String var3) Activity var1, RitScenes var2, String var3 方法说明: 展示激励视频广告接口
参数说明:
Activity :宿主activity
RitScenes:广告展示的场景
String:广告展示场景为 CUSTOMIZE_SCENES 时,自定义的场景信息
void setShowDownLoadBar(boolean var1) boolean var1 方法说明:设置展示下载bar
参数说明:boolean型
- True
- false
int getRewardVideoAdType() 方法说明:得到广告的交互类型
AD_TYPE_UNKNOWN //未知类型
AD_TYPE_COMMON_VIDEO //普通视频类型
AD_TYPE_PLAYABLE_VIDEO //video + playable 类型
AD_TYPE_PLAYABLE //playable类型
参数说明:无
long getExpirationTimestamp() 方法说明:返回有效期的截止时间,超过这个时间点,广告视为过期
参数说明:无
public interface RewardAdInteractionListener () 见RewardAdInteractionListener说明
RewardAdInteractionListener
参数 说明
onAdShow() 广告的展示回调
onAdVideoBarClick() 广告下载bar点击回调
onAdClose() 广告关闭回调
onVideoComplete() 视频播放完成回调
onSkippedVideo() 跳过视频播放回调
onRewardVerify() 奖励验证回调,开发者在需要在此回调中做奖励的发放

RewardVideoAdListener

方法 说明
onError() 广告请求失败回调 返回的错误码(code)表示广告请求失败的原因,详情请见链接
onRewardVideoCached() 广告视频本地加载完成的回调,可以在这个回调后直接播放本地视频
onRewardVideoCached(TTRewardVideoAd ad) 广告视频本地加载完成的回调,可以在这个回调后直接播放本地视频,直接使用参数对象来播放
onRewardVideoAdLoad() 广告加载完成的回调

注:为保证广告视频播放的流畅建议在onRewardVideoCached回调加载完毕后,再在主线程中调用showRewardVideoAd方法进行广告的展示。 展示广告完毕之后及时把广告对象置为null

//当mIsLoaded标识为true 代表广告视频本地加载完整 可直接开启一个主线程处理showRewardVideoAd
if (mttRewardVideoAd != null&&mIsLoaded) {
       //展示广告,并传入广告展示的场景
       mttRewardVideoAd.showRewardVideoAd(RewardVideoActivity.this, TTAdConstant.RitScenes.CUSTOMIZE_SCENES, "scenes_test");
       mttRewardVideoAd = null;
     } else {
        TToast.show(RewardVideoActivity.this, "请先加载广告");
 }

广告交互监听器

RewardAdInteractionListener mttRewardVideoAd.setRewardAdInteractionListener(new TTRewardVideoAd.RewardAdInteractionListener() {
	//广告的下载bar点击回调
    @Override
    public void onAdVideoBarClick() {
       
    }
	//视频广告关闭回调
    @Override
    public void onAdClose() {
       
    }
    //视频播放完成回调
    @Override
    public void onVideoComplete() {
       
    }
	//视频广告播放错误回调
    @Override
    public void onVideoError() {

    }

    //视频播放完成后,奖励验证回调,rewardVerify:是否有效,rewardAmount:奖励梳理,rewardName:奖励名称,code:错误码,msg:错误信息
    @Override
    public void onRewardVerify(boolean rewardVerify, int rewardAmount, String rewardName,int code,String msg) {

    }
	//视频广告跳过回调
    @Override
    public void onSkippedVideo() {

    }
   //视频广告展示回调
    @Override
    public void onAdShow() {

    }
});

onRewardVerify 回调说明:

  1. 不使用户服务端奖励验证的情况下onRewardVerify回调只校验视频播放状态或者进度,视频播放90%或者因播放器异常导致出现播放失败,那么穿山甲都会回调onRewardVerify,并且rewardVerify=true。
  2. 使用服务端奖励验证的情况下onRewardVerify回调返回的则是开发者服务端验证的结果。

综上: onRewardVerify 回调只是视频播放状态的一个结果或者是开发者返回的结果,不代表此次播放是否计费等广告业务指标。

onRewardVerify参数说明
参数 说明
rewardVerify 是否有效
rewardAmount 奖励数量,媒体平台创建代码位时配置的数值
rewardName 奖励名称,媒体平台创建代码位时配置的名称
code 错误码。 3300版本新增
msg msg错误信息。 3300版本新增

注:SDK3300版本onRewardVerify回调方法中新增int code,String msg参数
需要服务器判断:可根据rewardVerify作为判断条件 进行奖励的发放
无需服务器判断:rewardVerify默认是返回true 测试状态的代码位rewardVerify默认返回false

奖励发放机制

奖励发放逻辑可参考此文档: Link

服务器到服务器回调

服务器到服务器回调让您判定是否提供奖励给观看广告的用户。当用户成功看完广告时,会向您在穿山甲平台中配置的验证接口发送验证请求,由开发者来判断此次观看是否给用户发放奖励。
重点说明: 穿山甲服务端只是透传验证请求,不会在中间过程添加校验逻辑。为了保障开发者利益和用户体验,开发者可以在验证环节增加自己的校验逻辑。

回调方式说明

穿山甲服务器会以 GET 方式请求第三方服务的回调链接,并拼接以下参数回传:
user_id=%s&trans_id=%s&reward_name=%s&reward_amount=%d&extra=%s&sign=%s

字段名称 字段定义 字段类型 备注
sign 签名 string 签名
user_id tagid string 调用 SDK 透传
trans_id 交易 string 完成观看的唯一交易 ID
reward_amount 奖励数量 int 媒体平台创建代码位时配置的数值
reward_name 奖励名称 sting 媒体平台创建代码位时配置的名称
extra Extra string 调用 SDK 传入并透传,如无需要则为空

签名生成方式

appSecurityKey: 您在穿山甲媒体平台新建奖励视频代码位获取到的密钥
transId:交易 id

sign = sha256(appSecurityKey:transId)

Python 示例:

import hashlib
if __name__ == "__main__":
    trans_id = "6FEB23ACB0374985A2A52D282EDD5361u6643"
    app_security_key = "7ca31ab0a59d69a42dd8abc7cf2d8fbd"
    check_sign_raw = "%s:%s" % (app_security_key, trans_id)
    sign = hashlib.sha256(check_sign_raw).hexdigest()

约定返回参数

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

注意
按照SDK要求需要服务器判断的回调url是一个get请求 默认返回的是一个json字符串{"isValid": true}

示例:

{
    "isValid": true
}

销毁广告对象

//在Activity的onDestroy方法中清空广告对象
 @Override
    protected void onDestroy() {
        super.onDestroy();
        if (mttRewardVideoAd != null) {
            mttRewardVideoAd = null ;
        }
}

参考Demo

激励视频广告请参考Demo中的RewardVideoActivity

Did the content solve your problem?
Contact us