中文
登录
后可查看全部文档
开发测试/Android集成文档/模版渲染激励视频广告
模版渲染激励视频广告
最近更新 2024-05-21 16:14:35

简介

激励视频是一种全屏播放的视频广告,用户可以在观看完整的视频后获取奖励,视频广告播放结束后会显示结束页面,引导用户进行后续动作。目前激励视频广告的表现形式为:视频播放完展示Endcard页面、视频播放完展示互动页面或者直接出现互动广告。

支持的广告尺寸: 全屏横屏(宽高比16:9)、全屏竖屏(宽高比9:16)

配置说明

  • 开发者根据展示场景勾选视频播放方向:横版or竖版,展示过程中不可旋转。
  • 奖励名称和奖励数量依据自身项目需求设置即可,例如:奖励名称为金币,奖励数量:1000。V<5.2.0.4奖励发放实际情况按照平台配置参数进行下发,客户端接口已失效。
  • 奖励发放设置:
    • 当选择无需服务器判断时,开发者可以根据客户端onRewardVerify或onRewardArrived回调进行奖励的发放。onRewardVerify或onRewardArrived回调只校验视频播放状态或者进度,视频播放90%或者因播放器异常导致出现播放失败,那么穿山甲都会回调onRewardVerify/onRewardArrived,并且rewardVerify=true。
    • 当选择需要服务器判断时,开发者需要按照以下要求进行接口开发,并在平台上填写回调URL。服务器回调是指在用户在看完激励视频达到奖励条件时,穿山甲服务端会向开发者服务端发送一个验证申请,开发者服务端收到请求后判断是否给用户奖励,返回给穿山甲服务器true/false,最终客户端会给出onRewardVerify或onRewardArrived回调,开发者根据回调进行奖励发放,或者通过服务端接口验证结果进行奖励发放。onRewardVerify/onRewardArrived回调返回的则是开发者服务端验证的结果。

基础功能说明

构建广告请求及广告参数对象

使用初始化后的TTAdManager对象,创建广告请求对象TTAdNative。

复制

AdSlot用于请求广告前,传递部分广告配置参数。

接口

是否必填

类型

含义

setCodeId()

String

您在平台上申请的代码位Id,以9开头9位数字

setAdLoadType()

TTAdLoadType枚举

用于标注此次的广告请求用途为预加载(当做缓存)还是实时加载,方便后续为开发者优化相关策略

setMediaExtra()

String

用户透传信息,仅支持单个json对象格式,不可以嵌套json对象

复制

请求广告、展示广告

调用TTAdNative.loadRewardVideoAd(adSlot, adLoadListener) 加载广告。

复制

在onRewardVideoAdLoad 或 onRewardVideoCached 方法中获取到TTRewardVideoAd对象后,调用showRewardVideoAd方法展示广告。

复制

监听广告状态

在获取到TTRewardVideoAd对象之后,调用展示广告之前,调用setRewardAdInteractionListener设置交互监听器。

复制

广告展示过程中会回调Listener中的各种方法,开发者可进行相应逻辑处理。

监听奖励发放

在用户浏览广告达到一定时长等相关条件满足后,SDK会给开发者回调RewardAdInteractionListener.onRewardArrived 方法,表示奖励触发,建议开发者在收到此回调且参考各参数后,决定是否给用户发送奖励。

  • onRewardVerify参数说明

参数

说明

rewardVerify

是否有效

code

错误码。 3300版本新增

msg

msg错误信息。 3300版本新增

isRewardValid

奖励是否有效。4400版本新增

rewardType

奖励类型,0:基础奖励 >0:进阶奖励 。4400版本新增

extraInfo

奖励的额外参数。4400版本新增

  • 奖励发放说明

参数

类型

说明

isRewardValid

boolean

此次奖励是否有效

rewardType

int

奖励类型

基础奖励:0


进阶奖励:> 0

仅当配置了进阶奖励功能,才会回调 > 0的值

extraInfo

Bundle

使用key-value存储的其他信息:

reward_extra_key_error_code:错误码

reward_extra_key_error_msg:错误信息

reward_extra_key_reward_name:平台配置的奖励名称

reward_extra_key_reward_amount:平台配置的奖励数量

奖励发放机制分为客户端回调与服务端回调,具体可参考文档: 激励视频交互方式简介&奖励方法说明


监听下载状态

在获取到TTRewardVideoAd对象之后,调用展示广告之前,调用setDownloadListener设置下载状态监听器;-可选功能

复制

高级功能说明

在基础接入的基础上,本部分提供一些需要额外适配的能力,有助于丰富广告样式,提升收益,推荐使用。

进阶奖励功能

在用户浏览广告时,若用户进行了一些深度操作(例如完整的观看广告,主动点击到落地页浏览等),则在基础奖励的基础上给用户增发奖励,提升广告的转化率与收入。

接入说明

①适用范围:此功能双端SDK均需在4600及以上。

②权限等级:功能为白名单制。对开发者appid或者指定的rit进行加白。

③视频时长限制:进阶奖励仅针对视频素材时长>35s生效。

接口说明

复制

再看一个功能

用户在看完一个激励视频后通过进一步广告互动获取更多APP内激励,有利于用户体验与APP活跃市场,同时开发者也可借助该功能提升激励视频曝光量与收入,详情请参考激励视频再看一个 广告介绍

  • 示例代码
复制

在激励广告中显示奖励内容

  • 穿山甲激励广告增加「在广告中显示奖励内容」功能,根据开发者配置的奖励物品和数量,在激励视频广告播放过程中提示用户完成激励任务后将获取的奖励收益,以激发用户兴趣、观看更久更完整的视频广告,提升整体的CTR和收入。
  • 当前已支持在挽留弹窗中显示奖励内容,穿山甲还在持续创新更多的展示样式。

使用说明

①版本要求:V >= 5.2.0.4;

②权限等级:功能面向所有账户开放;

③若想使用此功能,必须在穿山甲平台-激励视频代码位创编中配置开启“是否在广告中显示奖励内容”开关。


④开启后,根据系统优选的结果,您设置的奖励物品名称奖励数量将有可能在广告播放过程中展示。开发者可以通过两种方案配置具体显示的奖励内容

  1. 在截图所示穿山甲平台的代码位创编页面中里输入奖励名称和数量。
  2. 在请求广告时传入奖励名称和数量,详见文档「接口改动」部分
  • 在实际使用时,会按照优先级 2 > 1 来展示,若奖励名称和数量任一为空,则认为此对值无效。
  • 奖励数量为1~5个数字整数值,奖励内容为1~10个英文字符长度的字符串。

⑤具体的使用示例与温馨提示

  • 奖励物品名称“金币”,奖励数量“500”,广告挽留弹窗提示用户继续看完视频可领取“500金币”;奖励物品名称“分钟免广告”,奖励数量“60”,挽留弹窗显示继续观看xxs可领取奖励“60分钟免广告”。
  • 建议开发者配置/回传用户可真实获取的奖励内容,避免用户对奖励预期与获取产生出入。
  • 推荐开发者通过接口回传的形式,以便更灵活、动态地下发奖励,在用户粒度个性化优化收益。

接口说明

在请求广告,构建AdSlot对象中,使用setRewardAmount与setRewardName方法,传入奖励名称与奖励数量。

复制

接口API

AdSlot

方法名

是否必须

类型

含义

setCodeId()

String

您在平台上申请的代码位Id,以9开头9位数字

setAdLoadType()

TTAdLoadType枚举

用于标注此次的广告请求用途为预加载(当做缓存)还是实时加载,方便后续为开发者优化相关策略

setMediaExtra()

String

用户透传信息,仅支持单个json对象格式,不可以嵌套json对象

RewardVideoAdListener

方法名

方法介绍

onError(int code, String message)

若加载中出错,会回调此方法

onRewardVideoAdLoad(TTRewardVideoAd ad)

广告基础信息加载完成,此方法是回调后是广告可调用展示的最早时机

onRewardVideoCached()

已废弃,不再推荐使用

onRewardVideoCached(TTRewardVideoAd ad)

广告基础信息与素材缓存完成,此时调用广告展示流畅,是展示广告的最理想时机

TTRewardVideoAd

方法

说明

setRewardAdInteractionListener(RewardAdInteractionListener listener)

设置广告交互监听,可监听广告的展示,跳过,奖励发放,退出等各个时机

showRewardVideoAd(Activity activity)

展示广告

getExpirationTimestamp()


获取广告过期时间戳,若超过这个时间点,此广告视为过期

setDownloadListener(TTAppDownloadListener listener)

监听广告触发的应用下载进度与状态

setRewardPlayAgainInteractionListener(RewardAdInteractionListener listener)


仅当代码位开启了观看下一个激励视频才可用

设置非首次广告的交互监听,可监听广告的展示,跳过,奖励发放等各个时机

setRewardPlayAgainController(RewardAdPlayAgainController listener)

仅当代码位开启了观看下一个激励视频才可用

通过回调动态控制再看广告的入口是否可展示及文案

RewardAdInteractionListener

方法名

方法介绍

onAdShow()

广告的展示回调

每个广告仅回调一次

onAdVideoBarClick()

广告的点击回调

onAdClose()

广告的关闭回调

onVideoComplete()

广告素材播放完成

onVideoError()

广告素材展示时出错

onRewardVerify(boolean rewardVerify, int rewardAmount, String rewardName, int errorCode, String errorMsg)

已废弃,请使用onRewardArrived替代


onRewardArrived(boolean isRewardValid, int rewardType, Bundle extraInfo)

奖励验证回调,开发者在需要在此回调中做奖励的发放

可在奖励发放小节中查看此方法参数的详细介绍

onSkippedVideo()

跳过视频播放回调

接入须知

Q:onRewardVerify(旧接口)和onRewardArrived(新接口)区别是什么?

A:①回调参数差异:

    1. onRewardVerify为旧的奖励接口:若rewardVerify为false,则取错误码errorCode,错误信息errorMsg进行处理;
    2. 新接口的实现为:若isRewardValid为false,则从extraInfo里取ErrorCode或者ErrorMsg再进行处理;

②支持功能差异:

    1. onRewardVerify回调接口:不支持进阶奖励,进阶奖励只会回调onRewardArrived回调,onRewardVerify回调接口只给基础奖励回调;
    2. onRewardArrived回调接口:读取isRewardValid的值,判断为true,同时读取rewardType的值,判断为>0,目前为1或2时,可以进行进阶奖励的发放,奖励数量可以参考extraInfo中的RewardProPose给出的建议;

③奖励名称数量取值差异:

    1. onRewardVerify回调接口:奖励名称从rewardName取,奖励数量从rewardAmount取进行处理;
    2. onRewardArrived回调接口:从extraInfo里取RewardName或者RewardAmount再进行处理;



本篇目录
联系我们