Help Center/Details/

激励视频

简介

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

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

权限

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

代码位ID创建参数说明:

  • 开发者根据展示场景勾选视频播放方向:横版or竖版
  • 奖励名称和奖励数量依据自身项目需求设置即可,例如:奖励名称为金币,奖励数量:1000
  • 奖励发放设置:
    • 当选择无需服务器判断时,开发者可以根据客户端nativeExpressRewardedVideoAdServerRewardDidSucceed回调进行奖励的发放。
    • 当选择需要服务器判断时,开发者需要按照以下要求进行接口开发,并在平台上填写回调URL。
      服务器回调是指在用户在看完激励视频达到奖励条件时,穿山甲服务端会向开发者服务端发送一个验证申请,开发者服务端收到请求后判断是否给用户奖励,返回给穿山甲服务器true/false,最终客户端会给出nativeExpressRewardedVideoAdServerRewardDidSucceed回调,开发者根据回调进行奖励发放,或者通过服务端接口验证结果进行奖励发放。

奖励发放机制

奖励发放逻辑可参考此文档: 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 交易id string 完成观看的唯一交易ID
reward_amount 奖励数量 int 媒体平台配置
reward_name 奖励名称 string 媒体平台配置
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()

返回约定:

返回 json 数据,字段如下:

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

回调URL格式事例如下:

{ 
   "isValid": true
}

注意:

服务器回调模式不是必须的,服务器模式只是增加了一次第三方服务器验证判断,具体的奖励的发放是由客户端完成。

模版激励视频广告

使用说明

模版激励视频使用BUNativeExpressRewardedVideoAd对象调用loadAdData方法请求广告,使用BUNativeExpressRewardedVideoAd对象调用showAdFromRootViewController:展示广告,通过设置BUNativeExpressRewardedVideoAdDelegate代理,获取广告、展示、点击、关闭等回调。

创建广告位对象、请求广告

BUNativeExpressRewardedVideoAd

请求广告时需要传入广告位对象,广告位对象创建时必须传入广告位ID

必传参数:

字段定义 字段名称 字段类型 备注
SlotID 广告位 NSString 代码位ID
userId tag_id NSString tag_id

可选传入参数:

字段定义 字段名称 字段类型 备注
rewardName 奖励名称 NSString 按照项目需求设置即可
rewardAmount 奖励数量 NSInteger 按照项目需求设置即可
extra 透传参数 NSString 应为json序列化后的字符串

使用BUNativeExpressRewardedVideoAd创建对象,使用BUNativeExpressRewardedVideoAd调用loadAdDat请求广告

 BURewardedVideoModel *model = [[BURewardedVideoModel alloc] init];
 model.userId = @"tag123";
 self.rewardedAd = [[BUNativeExpressRewardedVideoAd alloc] initWithSlotID:slotID rewardedVideoModel:model];
 self.rewardedAd.delegate = self;
 // optional
    self.rewardedAd.rewardPlayAgainInteractionDelegate = self.expressRewardedVideoAgainDelegateObj;
 [self.rewardedAd loadAdData];

接收广告加载结果

BUNativeExpressRewardedVideoAdDelegate

回调方法 注释
nativeExpressRewardedVideoAd:didFailWithError 返回的错误码(error)表示广告加载失败的原因,所有错误码详情请见链接。Link
nativeExpressRewardedVideoAdViewRenderFail:error 渲染失败,网络原因或者硬件原因导致渲染失败,可以更换手机或者网络环境测试。建议升级到穿山甲平台最新版本
nativeExpressRewardedVideoAdDidLoad 广告素材物料加载成功
nativeExpressRewardedVideoAdDidDownLoadVideo 视频下载完成

BUNativeExpressRewardedVideoAdDelegate回调说明

回调方法 注释
nativeExpressRewardedVideoAdDidLoad: 回调进入证明广告物料已成功加载
nativeExpressRewardedVideoAd: didFailWithError: 此回调方法中可定位具体的失败原因对应的错误码,打印error即可。所有错误码详情请见链接。Link
nativeExpressRewardedVideoAdCallback:withType: 此回调可知模版激励视频的广告类型
nativeExpressRewardedVideoAdDidDownLoadVideo 建议在此回调方法中进行广告的展示操作,可保证播放流畅和展示流畅,用户体验更好。
nativeExpressRewardedVideoAdViewRenderSuccess: 渲染成功回调。3100之后版本SDK,广告展示之后才会回调
nativeExpressRewardedVideoAdViewRenderFail: 渲染失败,网络原因或者硬件原因导致渲染失败,可以更换手机或者网络环境测试。建议升级到穿山甲平台最新版本
nativeExpressRewardedVideoAdWillVisible: 模版激励视频广告即将展示
nativeExpressRewardedVideoAdDidVisible: 模版激励视频广告已经展示
nativeExpressRewardedVideoAdWillClose: 模版激励视频广告即将关闭
nativeExpressRewardedVideoAdDidClose: 用户关闭广告时会触发此回调,注意:任何广告的关闭操作必须用户主动触发;
nativeExpressRewardedVideoAdDidClick: 点击回调方法
nativeExpressRewardedVideoAdDidClickSkip: 跳过回调方法
nativeExpressRewardedVideoAdDidPlayFinish: 视频正常播放完成时可触发此回调方法,当广告播放发生异常时,不会进入此回调;
nativeExpressRewardedVideoAdServerRewardDidSucceed: 异步请求的服务器验证成功回调,开发者需要在此回调中进行奖励发放。现在包括两个验证方法:1. C2C需要服务器验证2。S2S不需要服务器验证。nativeExpressRewardedVideoAdServerRewardDidFail:异步请求的服务器验证失败回调。可在此回调方法中打印error,定位具体失败的原因,或通过抓包定位具体原因,抓包地址:https://域名或者ip地址/api/ad/union/sdk/get_ads/ 提供返回的数据进行确认)到【留言反馈】-【技术类提问入口(技术类暂仅支持此入口的提问回复)】进行反馈,相关同学会为您处理
nativeExpressRewardedVideoAdDidCloseOtherController:interactionType:此回调在广告跳转到其他控制器时,该控制器被关闭时调用interactionType: 此参数可区分是打开的appstore/网页/视频广告详情页面

nativeExpressRewardedVideoAdServerRewardDidSucceed 回调说明:

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

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

通过设置BUNativeExpressRewardedVideoAdDelegate代理,获取广告的点击、关闭、播放完成等回调。其他代理方法可参见BUDExpressRewardedVideoViewController#pragma mark - BUNativeExpressRewardedVideoAdDelegate

展示广告

激励视频广告需要让用户主动选择去观看,给用户选择,不能强制用户观看激励视频广告。广告播放完成需要给用户发放相应的奖励。
调用showAdFromRootViewController:方法展示激励视频广告,此处需要传入当前展示的页面。一定要设置rootViewController,即展示广告和跳转落地页需要的viewController

展示激励视频广告

//show的时候会进行WKWebview的渲染,建议一次最多展示三个广告,如果超过3个会很大概率导致WKWebview渲染失败。当然一般情况下激励视频一次只会show一个
- (void)showRewardVideoAd {
    if (self.rewardedAd) {
        [self.rewardedAd showAdFromRootViewController:self];
    }
}

展示时机

在收到nativeExpressRewardedVideoAdDidDownLoadVideo回调后再允许用户观看广告,可保证播放流畅和展示流畅,用户体验更好。

- (void)nativeExpressRewardedVideoAdDidDownLoadVideo:(BUNativeExpressRewardedVideoAd *)rewardedVideoAd {
 //在此回调方法后进行广告的展示,可保证播放流畅和展示流畅,用户体验更好。
}

广告展示后重新加载广告

同一次请求的广告最多只能计一次展示,重复的展示会被系统过滤。因此建议开发者在用户观看完广告后在nativeExpressRewardedVideoAdDidClose回调里将原来的广告对象置为nil 保证广告对象为新的请求对象

- (void)nativeExpressRewardedVideoAdDidClose:(BUNativeExpressRewardedVideoAd *)rewardedVideoAd {
//在此回调方法中可进行广告的置空操作
}

注意事项

  1. 必须要设置rootViewController,用来处理广告跳转。SDK里所有的跳转均采用present的方式,请确保传入的rootViewController不能为空且没有present其他的控制器,否则会出现presentedViewController已经存在而导致present失败。
  2. 如选择服务器回调方式,请确保userId为NSString类型且不为空,并保证回调URL 格式为
{
    "isValid": true
}
  1. nativeExpressRewardedVideoAdViewRenderSuccess渲染成功回调在广告展示后
  2. 为保证播放流畅和展示流畅,用户体验更好,在收到nativeExpressRewardedVideoAdDidDownLoadVideo回调后进行广告的展示
  3. extra透传参数应为json序列化后的字符串,确保不为空
  4. 判断广告是否有效直接使用self.rewardedAd判断即可。目前isAdValid字段已废弃,请不要使用此字段判断广告是否有效
  5. 个性化模板广告为了优化展示速度,会使用本地模板,请求时会拦截相关数据.如果接入方正在使用H5的页面发送请求,会造成请求body清空,其他逻辑不变.如果使用body传参请更换其他方式.例如:jsBridge方式。
  6. 广告的关闭操作,必须用户主动触发,客户端不能进行代码层面的强制关闭操作

资源

详细接入可参照Demo中的BUDExpressRewardedVideoViewController类,广告加载请求部分可参照loadRewardVideoAdWithSlotID方法,广告展示部分可参照showRewardVideoAd方法

SDK渲染激励视频广告

使用说明

SDK渲染激励视频使用BURewardedVideoAd对象调用loadAdData方法请求广告,使用BURewardedVideoAd对象调用showAdFromRootViewController:展示广告,通过设置BURewardedVideoAdDelegate代理,获取广告、展示、点击、关闭等回调。

创建广告位对象、请求广告

BURewardedVideoAd

请求广告时需要传入广告位对象,广告位对象创建时必须传入广告位ID

每次需要生成新的BURewardedVideoAd对象调用loadAdData方法请求最新激励视频,请勿重复使用本地缓存激励视频多次展示

必传参数:

字段定义 字段名称 字段类型 备注
SlotID 广告位 NSString 代码位ID
userId tag_id NSString tag_id

可选传入参数:

字段定义 字段名称 字段类型 备注
rewardName 奖励名称 NSString 按照项目需求设置即可
rewardAmount 奖励数量 NSInteger 按照项目需求设置即可
extra 透传参数 NSString 应为json序列化后的字符串,仅支持单个json对象格式,不可以嵌套json对象

使用BURewardedVideoAd创建对象,使用BURewardedVideoAd调用loadAdData请求广告

//保证每次请求的广告对象为新的广告对象,避免重复使用广告同一个对象进行广告请求
BURewardedVideoModel *model = [[BURewardedVideoModel alloc] init];
model.userId = @"tag123";
self.rewardedVideoAd = [[BURewardedVideoAd alloc] initWithSlotID:slotID rewardedVideoModel:model];
self.rewardedVideoAd.delegate = self;
// optional
    self.rewardedVideoAd.rewardPlayAgainInteractionDelegate = self.rewardedVideoAgainDelegateObj;
[self.rewardedVideoAd loadAdData];

接收广告加载结果

BURewardedVideoAdDelegate

回调方法 注释
rewardedVideoAd:didFailWithError: 返回的错误码(error)表示广告加载失败的原因,所有错误码详情请见链接。Link
rewardedVideoAdDidLoad: 广告素材物料加载成功
rewardedVideoAdVideoDidLoad: 视频下载完成

BURewardedVideoAdDelegate回调说明

回调方法 注释
rewardedVideoAdDidLoad: 物料加载成功回调
rewardedVideoAd: didFailWithError: 加载失败回调
rewardedVideoAdVideoDidLoad: 视频下载成功回调,建议在此回调方法中进行广告的展示,可保证广告播放流畅展示,用户体验较好。
rewardedVideoAdWillVisible: 当广告即将显示时,会进入此回调方法
rewardedVideoAdDidVisible: 当广告已经显示时,会进入此回调方法
rewardedVideoAdWillClose: 当广告即将被关闭时,会进入此回调方法
rewardedVideoAdDidClose: 关闭回调,当广告关闭时可才此回调中进行相关的逻辑
处理rewardedVideoAdDidClick: 当广告被点击时,会进入此回调方法
rewardedVideoAdDidPlayFinish:didFailWithError: 当广告播放完成或者发生错误时会进入此回调,打印error即可。所有错误码详情请见链接。Link
rewardedVideoAdServerRewardDidSucceed: verify: 异步请求的服务器验证成功回调
rewardedVideoAdServerRewardDidFail: 异步请求的服务器验证失败回调
rewardedVideoAdServerRewardDidFail: error: 异步请求的服务器验证失败回调,此回调方法中可打印失败原因,即打印error即可。所有错误码详情请见链接。Link
rewardedVideoAdDidClickSkip: 点击跳过回调(此功能需单独申请,cpm负向影响)
rewardedVideoAdCallback: withType: 此回调可知激励视频的广告类型

通过设置BURewardedVideoAdDelegate代理,获取广告的点击、关闭、播放完成等回调。其他代理方法可参见BUDRewardedVideoAdViewController类#pragma mark - BURewardedVideoAdDelegate

展示广告

激励视频广告需要让用户主动选择去观看,给用户选择,不能强制用户观看激励视频广告。广告播放完成需要给用户发放相应的奖励。

调用showAdFromRootViewController: 方法展示激励视频广告,此处需要传入当前展示的页面。一定要设置rootViewController,即展示广告和跳转落地页需要的viewController

展示激励视频广告

- (void)showRewardVideoAd {
  if (self.rewardedVideoAd) {
     [self.rewardedVideoAd showAdFromRootViewController:self];
   }
 }

展示时机

在收到rewardedVideoAdVideoDidLoad回调后再允许用户观看广告,可保证播放流畅和展示流畅,用户体验更好。

- (void)rewardedVideoAdVideoDidLoad:(BURewardedVideoAd *)rewardedVideoAd {
   //此回调方法后进行广告的展示,可保证播放流畅和展示流畅,用户体验更好。
}

广告展示后重新加载广告

同一次请求的广告最多只能计一次展示,重复的展示会被系统过滤。因此建议开发者在用户观看完广告后在rewardedVideoAdDidClose回调里将原来的广告对象置为nil 保证广告对象为新的请求对象

- (void)rewardedVideoAdDidClose:(BURewardedVideoAd *)rewardedVideoAd {
//可在此回调中将广告对象置为nil
}

注意事项

  1. 必须要设置rootViewController,用来处理广告跳转。SDK里所有的跳转均采用present的方式,请确保传入的rootViewController不能为空且没有present其他的控制器,否则会出现presentedViewController已经存在而导致present失败。
  2. 如选择服务器回调方式,请确保userId为NSString类型且不为空,并保证回调URL格式为
{
    "isValid": true
}
  1. 为保证播放流畅和展示流畅,用户体验更好,在收到rewardedVideoAdVideoDidLoad回调后进行广告的展示
  2. extra透传参数应为json序列化后的字符串,确保不为空
  3. 判断广告是否有效直接使用self.rewardedAd判断即可。目前isAdValid字段已废弃,请不要使用此字段判断广告是否有效
  4. 广告的关闭操作必须用户主动触发,客户端不能进行代码层面的强制关闭操作

资源

详细接入可参照Demo中的BUDRewardedVideoAdViewController类,广告加载请求部分可参照loadRewardVideoAdWithSlotID:方法,广告展示部分可参照showRewardVideoAd方法

AdMob通过CustomEvent Adapter方式聚合激励视频

通过AdMob聚合激励视频有两种方式,第一种是通过AdMob广告联盟方式,第二种是通过CustomEvent Adapter方式聚合。目前今日头条暂支持第二种方式,需要您配置CustomEvent并实现CustomEvent Adapter。请参考 Rewarded Video Adapters官网指南

请求激励视频方式请参考 Rewarded Video 官方指南

广告测试请参考 Test Ads

请注意以下几点:
  • 配置CustomEvent时,Class Name与实现的Adapter类名要保持统一,否则无法调起adapter
  • iOS simulator默认是 Enable test device类型设备,只能获取到Google Test Ads,无法取得今日头条测试广告,若要测试今日头条广告,请使用iOS真机设备,并且不要添加成AdMob TestDevices
Did the content solve your problem?
Contact us