帮助中心

中文

后可查看全部文档

帮助文档

新手引导

合作注册

流量管理

业务规范

开发测试

GroMore

电商联盟

内容输出

闭环电商

财务结算

AdSpark（增长参谋）

开发测试/Android集成文档/模版渲染激励视频广告

模版渲染激励视频广告

最近更新 2026-03-19 15:53:38

一、简介

激励视频是一种全屏播放的视频广告，一般展示场景是用户需要游戏复活、解锁游戏关卡、获得享受应用中的某些功能时由用户选择观看激励视频广告并获得相应激励。未经用户允许时(如未点击播放按钮)不能自动播放激励视频，用户可以在观看完整的视频后获取奖励。

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

二、配置说明

开发者根据展示场景勾选视频播放方向：横版or竖版，展示过程中不可旋转。
奖励发放设置：详情请查看本章【高级功能-激励视频奖励下发】说明：当选择无需服务器判断时，开发者可以根据客户端的onRewardArrived回调进行奖励的发放。该回调只校验视频播放状态或者进度，视频播放90%或因播放器异常导致出现播放失败，穿山甲都会回调onRewardArrived，并且rewardVerify=true。当选择需要服务器判断时，开发者需要按照以下要求进行开发，并在平台上填写奖励回调URL。服务器回调：是指在用户在看完激励视频达到奖励下发条件时，穿山甲服务端会向开发者服务端发送一个验证申请，开发者服务端收到请求后判断是否给用户奖励，返回给穿山甲服务器true/false，最终客户端会给出onRewardArrived回调，开发者根据回调进行奖励发放或者通过服务端接口验证结果进行奖励发放。

三、基础功能

1. 构建请求参数

1.1 使用示例

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

复制

构建广告请求参数AdSlot

复制

1.2 接口说明

接口	是否必填	类型	含义
setCodeId()	是	String	您在平台上申请的代码位Id，9开头9位数字
setAdLoadType()	否	TTAdLoadType	用于标注此次的广告请求用途为预加载（当做缓存）还是实时加载，方便后续为开发者优化相关策略
setMediaExtra()	否	String	用户透传信息，仅支持单个json对象格式，不可以嵌套json对象

2. 请求及展示广告

调用TTAdNative.loadRewardVideoAd（adSlot, adLoadListener) 加载广告，在 onRewardVideoCached 方法中获取到TTRewardVideoAd对象后，调用showRewardVideoAd方法展示广告。

2.1 使用示例

复制

2.2 接口说明

RewardVideoAdListener

方法	说明
onError(int code, String message)	若加载中出错，会回调此方法
onRewardVideoAdLoad(TTRewardVideoAd ad)	广告基础信息加载完成，此方法是回调后是广告可调用展示的最早时机
onRewardVideoCached(TTRewardVideoAd ad)	广告基础信息与素材缓存完成，此时调用广告展示流畅，是展示广告的最理想时机

TTRewardVideoAd

方法	说明
showRewardVideoAd(Activity activity)	展示广告
getExpirationTimestamp()	获取广告过期时间戳，若超过这个时间点，此广告视为过期
setRewardAdInteractionListener(RewardAdInteractionListener listener)	设置广告交互监听，监听广告的展示，跳过，奖励发放，退出等行为详情查看【监听广告行为】说明
setDownloadListener(TTAppDownloadListener listener)	监听广告触发的应用下载进度与状态详情查看【监听下载状态】说明

3. 监听广告行为

在获取到TTRewardVideoAd对象之后，展示广告之前调用ad.setRewardAdInteractionListener设置广告交互监听器。可监听广告的展示，跳过，奖励发放，退出等行为，开发者可进行相应逻辑处理。

3.1使用示例

复制

3.2 接口说明

方法名	方法介绍
onAdShow()	广告的展示回调
onAdVideoBarClick()	广告的点击回调
onAdClose()	广告的关闭回调
onVideoComplete()	广告素材播放完成
onVideoError()	广告素材展示时出错
onRewardArrived(boolean isRewardValid, int rewardType, Bundle extraInfo)	奖励验证回调，开发者在需要在此回调中做奖励的发放从extraInfo里取RewardName或者RewardAmount再进行处理若isRewardValid为false，则从extraInfo里取ErrorCode或者ErrorMsg再进行处理详情查看【高级功能-激励视频奖励下发说明】
onSkippedVideo()	跳过视频播放回调

4. 监听下载状态

在获取到TTRewardVideoAd对象之后，展示广告之前，调用setDownloadListener设置下载状态监听下载进度和状态；

复制

四、高级功能

1. 激励广告中显示奖励内容

穿山甲激励广告支持「在广告中显示奖励内容」功能，根据开发者配置的奖励物品和数量，在激励视频广告播放过程中提示用户完成激励任务后将获取的奖励收益，以激发用户兴趣、观看更完整的视频广告，提升整体的CTR和收入。

1.1 使用说明

若想使用此功能，需在创建激励视频代码位时配置开启“在广告中显示奖励内容”开关。开启后您设置的奖励物品名称、奖励数量会基于模版优选逻辑将有可能在广告播放过程中展示。开发者可以通过以下两种方案配置具体显示的奖励内容。

方案一：在穿山甲平台-代码位创编页面输入奖励名称和数量。

方案二(优先级较高)：在请求广告时使用setRewardAmount与setRewardName方法传入奖励名称和数量，详见文档「接口改动」部分。

若奖励名称和数量任一为空，则认为此对值无效。
奖励数量为1~5个数字整数值，奖励内容为1～10个英文字符长度的字符串。

P1:方案一 P2:方案二

1.2 使用示例

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

2. 激励视频奖励下发说明

为满足开发者对激励视频奖励发放逻辑处理，穿山甲广告变现为开发者提供了客户端和服务端奖励下发回调校验功能，开发者可基于此功能对满足奖励发放条件的用户进行发放奖励。

2.1 奖励发放条件

纯视频激励视频：

一般视频时长为5~60s，可通过观看足够视频时长获取奖励，奖励回调下发时即成功领奖。

互动类激励视频：

一般视频时长为5s~60s，激励倒计时过程中会出现互动玩法。可通过互动完成相应任务（或关闭互动玩法并观看达到计时时长要求）从而获取奖励，奖励回调下发时即成功领奖。

2.2 奖励回调方法说明

开发者不管使用服务端验证还是客户端验证都可以通过奖励验证回调方法进行奖励发放。

客户端回调的优势：对接简单、高效，通过接口回调结果在客户端完成奖励发放即可。
服务端回调的优势：开发者可在服务端进行二次校验，支持透传参数到服务器。

2.2.1 客户端回调

穿山甲根据“奖励发放条件”，直接通过onRewardArrived回调给到开发者客户端是否发放奖励，对接相对简单。奖励验证回调涵盖目前所有激励视频播放异常的场景，包括非用户主动操作导致的视频无法完成播放。

使用示例

复制

接口说明

参数	类型	说明
isRewardValid	boolean	此次奖励是否有效
rewardType	int	奖励类型：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：平台配置的奖励数量

2.2.2 服务端回调【可选】

服务器回调是指用户在看完激励视频达到奖励下发条件时，穿山甲服务端会向开发者服务端发送一个验证申请，开发者服务端收到请求后判断是否给用户奖励，返回给穿山甲服务器true/false，最终客户端会通过onRewardArrived回调透传奖励下发结果，开发者根据回调进行奖励发放或者通过服务端接口验证结果进行奖励发放。使用说明详见激励视频交互方式简介&奖励方法说明

本篇目录