激励视频
一.集成建议
主要介绍在项目中如何集成 TradPlus SDK的激励视频：
- （1）激励视频广告一般是全屏的15-30s的视频，调用时机是在给用户奖励或者获得某些特定物品时展示广告；当用户看完广告，开发者可以在OnRewardedVideoAdReward回调中下发奖励发放给用户。目前TP不支持服务器回调（S2S）的激励下发机制，但是可以使用广告平台的服务器回调功能，请参考激励视频服务器激励(S2S)说明。
- （2）激励视频广告是三方广告平台提供的activity，一般不支持做定制或者修改。创建广告位对象和展示广告的时候需要传Activity。
- （3）激励视频广告一般需要预加载，在需要展示激励视频前判断HasRewardedVideo()是否准备好，准备好后可以调ShowRewardedVideo()
注意事项
- （1）禁止在
OnRewardedVideoAdFailed回调中执行广告加载的方法，否则会引起多个无用请求。 - （2）禁止在
OnRewardedVideoAdLoaded回调中直接执行广告展示的方法。SDK有广告会过期自动补充功能。如果在OnRewardedVideoAdLoaded回调中执行ShowRewardedVideo()，开发者会无法精准控制广告展示的时机。
二.API说明
1.加载类API
- 初始化广告位、请求广告
| 方法 | 说明 |
|---|---|
| TradPlus.LoadRewardedVideoPluginsForAdUnits("AdUnitId"); | 初始化广告位。 仅初始化时调用一次。 |
| TradPlus.HasRewardedVideo("AdUnitId"); | 检测是否有可用广告。 |
- 展示广告(方法一)
| 方法 | 说明 |
|---|---|
| TradPlus.ShowRewardedVideo("AdUnitId"); | 展示广告 |
| TradPlus.RewardedVideoEntryAdScenario("AdUnitId"); | 进入广告场景。 |
- 展示广告(方法二)
| 方法 | 说明 |
|---|---|
| TradPlus.ShowRewardedVideo("AdUnitId","sceneId"); | 展示广告并设置广告场景ID 使用该方法必须调用 TradPlus.RewardedVideoEntryAdScenario("AdUnitId","sceneId")。 |
| TradPlus.RewardedVideoEntryAdScenario("AdUnitId","sceneId"); | 进入广告场景，并传入sceneId广告场景ID。(可选) |
- 参数说明
| 参数 | 说明 |
|---|---|
| 广告位ID adUnitId | TradPlus后台创建。应用管理——添加应用——添加广告位。注意广告类型创建错误会导致广告展示失败，例如用标准原生的广告位去请求激励视频广告。 |
| 广告场景ID sceneId | TradPlus后台创建。应用管理——广告场景。具体如何使用，请看广告场景的调用时机和用途说明。 |
2.监听回调API
- 监听回调中的参数说明
| 参数 | 说明 |
|---|---|
| TPAdInfo | 广告位ID、三方广告平台、ecpm等信息，具体请参考回调信息说明。 |
| errorMsg | 广告请求失败、广告展示失败的错误信息，具体请参考错误码、错误信息说明。 |
- 广告位维度回调监听 V6.4.5新增API
| 方法 | 参数 | 说明 |
|---|---|---|
| OnRewardedVideoAdLoaded | string tpAdInfo | 广告加载成功。 |
| OnRewardedVideoAdFailed | string adUnitId ， string errorMsg | 广告加载失败。 |
| OnRewardedVideoAdImpression | string tpAdInfo | 广告被展示，老版本API为 TradPlusManager.OnRewardedVideoShownEvent。 |
| .OnRewardedVideoAdClicked | string tpAdInfo | 广告被点击，老版本API为 TradPlusManager.OnRewardedVideoClickedEvent。 |
| OnRewardedVideoAdClosed | string tpAdInfo | 广告被关闭，老版本API为TradPlusManager.OnRewardedVideoDismissedEvent。 |
| OnRewardedVideoAdReward | string tpAdInfo | 广告奖励回调，老版本API为TradPlusManager.OnRewardedVideoReceivedRewardEvent。 |
| OnRewardedVideoAdVideoError | string tpAdInfo， string errorMsg | 广告播放失败。 V7.3.0新增回调参数 errorMsg。 |
| string tpAdInfo | “再看一次”奖励回调。 V7.4.0新增，目前仅快手和头条国内支持(需要申请)。 V8.1.0.1废弃，使用OnRewardedVideoPlayAgainReward监听。 | |
| OnRewardedVideoPlayStart | string tpAdInfo | 视频播放开始。 Android V8.1.0.1新增 iOS V7.8.10新增 |
| OnRewardedVideoPlayEnd | string tpAdInfo | 视频播放结束。 Android V8.1.0.1新增 iOS V7.8.10新增 |
- 广告源维度回调监听 (可选) V6.4.5新增API
| 方法 | 参数 | 说明 |
|---|---|---|
| OnRewardedVideoAdAllLoaded | bool isSuccess， string adUnitId | 广告位的状态。loadAd()完毕后用于判断是否有可用广告；true表明有可用广告，false表明没有可用广告。 老版本API为 TradPlusManager.OnRewardedVideoAllLoadedEvent。 |
| OneRewardedVideoLayerLoadFailed | string tpAdInfo， string errorMsg | 后台配置多个广告源，每个广告源加载失败后会都会回调一次。 老版本API为 TradPlusManager.OnRewardedVideoFailedEvent。 |
| OneRewardedVideoLayerLoaded | string tpAdInfo | 后台配置多个广告源，每个广告源加载成功后会都会回调一次。 老版本API为 TradPlusManager.OnRewardedVideoLoadedEvent。 |
| string tpAdInfo | 请求广告后，广告开始加载。 V7.9.0 废弃。 | |
| OneRewardedVideoLayerStartLoad | string tpAdInfo | 每层waterfall 向三方广告源发起请求前，触发的回调。 V7.9.0 新增回调。 |
| OnRewardedVideoAdStartLoad | string adUnitId | 每次调用load方法时返回的回调 V7.9.0 新增回调。 |
| OnRewardedVideoBiddingStart | string tpAdInfo | Bidding开始加载。 |
| OnRewardedVideoBiddingEnd | string tpAdInfo， string errorMsg | Bidding加载完成。 V7.3.0新增回调参数 errorMsg。 |
- “再看一次” (可选) 仅快手、穿山甲支持（Android V8.1.0.1， iOS V7.8.10新增）
| 方法 | 参数 | 说明 |
|---|---|---|
| OnRewardedVideoAgainImpression | string tpAdInfo | “再看一次”展示 |
| OnRewardedVideoAgainVideoStart | string tpAdInfo | “再看一次”视频播放开始 |
| OnRewardedVideoAgainVideoEnd | string tpAdInfo | “再看一次”视频播放结束 |
| OnRewardedVideoAgainVideoClicked | string tpAdInfo | “再看一次”点击 |
| OnRewardedVideoPlayAgainReward | string tpAdInfo | “再看一次”奖励 |
- 下载监听(可选) 仅快手、穿山甲、广点通支持（Android V8.1.0.1）
| 方法 | 参数 | 说明 |
|---|---|---|
| OnRewardedVideoDownloadStart | string tpAdInfo, string networkinfo | 开始下载回调。 TPAdInfo：广告的信息对象，具体请参考上文回调信息说明 开发者可通过 解析 json“networkinfo”获得： totalBytes：文件总大小（单位：字节） currBytes：当前已下载的大小（单位：字节） fileName：文件名 appName：文件对应的应用名称 |
| OnRewardedVideoDownloadUpdate | string tpAdInfo, string networkinfo | 下载进度更新回调。 参数意义同上。 |
| OnRewardedVideoDownloadPause | string tpAdInfo, string networkinfo | 暂停下载回调。 参数意义同上。 |
| OnRewardedVideoDownloadFinish | string tpAdInfo, string networkinfo | 下载完成回调。 参数意义同上。 |
| OnRewardedVideoDownloadFail | string tpAdInfo, string networkinfo | 下载失败回调。 参数意义同上。 |
| OnRewardedVideoInstalled | string tpAdInfo, string networkinfo | Apk安装完成回调。 参数意义同上。 |
三.示例代码
// 1、初始化广告位。仅调用一次。
TradPlus.LoadRewardedVideoPluginsForAdUnits("AdUnitId");
// 2、加载广告。广告位ID在TradPlus后台创建。
TradPlus.RequestRewardedVideo("AdUnitId");
// 3、判断是否有可用广告
if (TradPlus.HasRewardedVideo("AdUnitId"))
{
// 4、展示
TradPlus.ShowRewardedVideo("AdUnitId");
}