激励视频
一、集成建议#
主要介绍在Android项目中如何集成 TradPlus SDK的激励视频：
- 激励视频广告一般是全屏的15-30s的视频，调用时机是在给用户奖励或者获得某些特定物品时展示广告；当用户看完广告，开发者可以在onAdReward回调中下发奖励发放给用户。支持服务器激励，请参考激励视频服务器激励(S2S)说明。
- 激励视频广告是三方广告平台提供的activity，一般不支持做定制或者修改。创建广告位对象和展示广告的时候需要传Activity。
- 激励视频广告一般需要预加载，在需要展示激励视频前判断isReady()是否准备好，准备好后可以调showAd()。
注意事项#
- 不建议在
oneLayerLoadFailed和onAdFailed回调中执行广告加载的方法。对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。 - 【V9.9.0.1以下版本】 不建议在
onAdLoaded回调中直接执行广告展示的方法：- SDK有广告过期自动补充和自动加载功能，加载成功后会回调
onAdLoaded onAdLoaded回调中直接showAd()，会导致过期补充或自动加载成功后弹出广告影响用户体验- 建议：开发者记录
onAdLoaded状态，在需要展示广告的地方，先判断isReady()返回true，再展示广告
- SDK有广告过期自动补充和自动加载功能，加载成功后会回调
- 【V9.9.0.1 + 】优化回调机制，调用一次
loadAd()才会收到一次loaded回调。- 开发者可以直接在
onAdLoaded回调中执行广告展示
- 开发者可以直接在
二、TPReward API说明#
1、创建广告位对象#
| 方法 | 说明 |
|---|---|
| TPReward(Activity activity, String adUnitId) | 仅调用一次。 以下广告平台时必须传入Activity: IronSource 、Kidoz、Maio、GDT（奖励式插屏全屏视频）、TapTap、章鱼移动 ,否则会导致广告无法加载成功。 adUnitId是在TP平台创建的广告位ID。 |
2、加载、展示广告#
| 方法 | 说明 |
|---|---|
| loadAd() | 请求广告。 |
| isReady() | 检测是否有可用广告。 V6.2.4新增API。 true为有可用广告。 |
| entryAdScenario(String sceneId) | 进入广告场景。 广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数，所以请在准确的位置调用。 |
| showAd(Activity activity, String sceneId) | 展示广告。 参数1: 以下广告平台时必须传入Activity：Awesome、UnityAds、Fyber、Admob、Huawei、 Kuaishou、Mimo、Sigmob、GDT、Toutiao（国内）、Pangle（海外）、快手海外 ,否则会导致广告加载成功，但无法展示。 参数2： sceneId 广告场景ID 是可选参数，开发者需和 entryAdScenario(sceneId)配套使用。不调用entryAdScenario(sceneId)，可以直接传空字符串。 |
- 参数说明
| 参数 | 说明 |
|---|---|
| adUnitId | 广告位ID，TradPlus后台创建。应用管理——添加应用——添加广告位。 注意广告类型创建错误会导致广告展示失败，例如用标准原生的广告位去请求激励视频广告。 |
| sceneId | 广告场景ID，TradPlus后台创建。应用管理—— 广告场景。 具体如何使用，请看广告场景的调用时机和用途说明。 |
3、清除缓存广告#
| 方法 | 说明 |
|---|---|
| clearCacheAd() | V7.4.30.1开始支持。 主要使用场景：游戏或应用切换用户后需要清理之前已加载完成的激励视频广告缓存。 |
4、监听回调#
| 方法 | 说明 |
|---|---|
| setAdListener(RewardAdListener adListener) | 设置广告监听。 其中RewardAdListener是需要实现广告事件回调的接口类。 |
| setAllAdLoadListener(LoadAdEveryLayerListener everyLayerListener) | 设置单个源维度的监听回调(可选) V6.4.5新增API。其中LoadAdEveryLayerListener是需要实现广告事件回调的接口类。单个源维度是指TP端的一个广告位下配置多个广告源缓存，每个源的回调。 |
| setDownloadListener(DownloadListener downloadListener) | 设置下载监听回调(可选 )。 快手、穿山甲等国内源支持。 V8.1.0.1新增API。 |
| setRewardAdExListener(RewardAdExListener rewardAdExListener) | 设置“再看一次”回调(可选 )。 快手、穿山甲等国内源支持。 V8.1.0.1新增API。 |
- 监听回调中的参数说明 V6.2.4新增API
| 参数 | 说明 |
|---|---|
| TPAdInfo | 广告位ID、三方广告平台、ecpm等信息，具体请参考回调信息说明。 |
| TPAdError | 广告请求失败、广告展示失败的错误码、错误信息，具体请参考错误码、错误信息说明。 |
- RewardAdListener（广告位维度）
| 方法 | 说明 |
|---|---|
| onAdClicked(TPAdInfo tpAdInfo) | 广告被点击。V9.7.10.1新增的Taptap暂不支持点击回调。 |
| onAdImpression(TPAdInfo tpAdInfo) | 广告被展示。 |
| onAdClosed(TPAdInfo tpAdInfo) | 广告被关闭。 |
| onAdLoaded(TPAdInfo tpAdInfo, TPBaseAd tpBaseAd) | 广告加载成功。 V9.9.0.1优化回调机制，开发者主动调用一次load才会对应回调一次loaded,不调用不回调。 |
| onAdFailed(TPAdError error) | 广告加载失败。 |
| onAdReward(TPAdInfo tpAdInfo) | 广告奖励。 |
| onAdVideoError(TPAdInfo tpAdInfo, TPAdError tpAdError) | 广告展示失败。 V7.3.0新增回调参数TPAdError。 |
| “再看一次”奖励回调。 V7.4.0新增，目前仅快手和头条国内支持(需要申请)。 V8.1.0.1 废弃。 开发者可通过设置setRewardAdExListener获取“再看一次奖励”回调。 | |
| onAdVideoStart(TPAdInfo tpAdInfo) | 视频播放开始。 V8.1.0.1新增。 |
| onAdVideoEnd(TPAdInfo tpAdInfo) | 视频播放结束。 V8.1.0.1新增。 |
- LoadAdEveryLayerListener（可选）（单个源维度）V6.4.5新增
| 方法 | 说明 |
|---|---|
| onAdAllLoaded(boolean isSuccess) | 广告位的状态。loadAd()完毕后用于判断是否有可用广告，true表明有可用广告，false表明没有可用广告。 |
| oneLayerLoadFailed(TPAdError adError, TPAdInfo adInfo) | 配置多个广告源，每个广告源加载失败后都会回调一次。 |
| oneLayerLoaded(TPAdInfo adInfo) | 配置多个广告源，每个广告源加载成功后都会回调一次。 |
| 请求广告后，广告开始加载。 V7.9.0 废弃。 | |
| oneLayerLoadStart(TPAdInfo tpAdInfo) | 每层waterfall 向三方广告源发起请求前，触发的回调。V7.9.0 新增。 |
| onAdStartLoad(String adUnitId) | 每次调用load方法时返回的回调。V7.9.0 新增。 |
| onBiddingStart(TPAdInfo tpAdInfo) | Bidding开始加载。 |
| onBiddingEnd(TPAdInfo tpAdInfo, TPAdError tpAdError) | Bidding加载完成。 V7.3.0新增回调参数TPAdError。 |
| onAdIsLoading(String adUnitId) | 调用load之后如果收到此回调，说明广告位仍处于加载状态，无法触发新的一轮广告加载。 V9.0.0新增回调。 |
- setDownloadListener（可选）（部分国内源支持）V8.1.0.1新增
| 方法 | 参数 | 说明 |
|---|---|---|
| onDownloadStart | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 开始下载回调。 TPAdInfo：广告的信息对象，具体请参考上文回调信息说明 totalBytes：文件总大小（单位：字节） currBytes：当前已下载的大小（单位：字节） fileName：文件名称 appName：文件对应的应用名称 |
| onDownloadUpdate | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName,int progress | 下载进度更新回调。 参数意义同上。 |
| onDownloadPause | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 暂停下载回调。 参数意义同上。 |
| onDownloadFinish | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 下载完成回调。 参数意义同上。 |
| onDownloadFail | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 下载失败回调。 参数意义同上。 |
| onInstalled | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | Apk安装完成回调。 参数意义同上。 |
- setRewardAdExListener（可选）（部分国内源支持）V8.1.0.1新增
| 方法 | 说明 |
|---|---|
| onAdAgainVideoClicked(TPAdInfo tpAdInfo) | “再看一次”广告被点击。 |
| onAdAgainImpression(TPAdInfo tpAdInfo) | “再看一次”广告被展示。 |
| onAdAgainVideoStart(TPAdInfo tpAdInfo) | “再看一次”广告视频播放开始。 |
| onAdAgainVideoEnd(TPAdInfo tpAdInfo) | “再看一次”广告视频播放结束。 |
| onAdPlayAgainReward(TPAdInfo tpAdInfo) | “再看一次”广告奖励回调。 |