中文
登录
后可查看全部文档
开发测试/iOS集成文档/模板渲染激励视频广告
模板渲染激励视频广告
最近更新 2026-03-19 15:52:35

一、简介

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

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

注意事项:

  • 广告监听:nativeExpressRewardedVideoAdViewRenderSuccess渲染成功回调在广告展示后为保证播放流畅和展示流畅,在收到nativeExpressRewardedVideoAdDidDownLoadVideo回调后进行广告的展示
  • 其他配置必须要设置rootViewController用来处理广告跳转。SDK里所有的跳转均采用present的方式,请确保传入的rootViewController不能为空且没有present其他的控制器,否则会出现presentedViewController已经存在而导致present失败。extra透传参数应为json序列化后的字符串,确保不为空判断广告是否有效直接使用self.rewardedAd判断即可。请不要使用isAdValid字段判断广告是否有效

二、配置说明

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

三、基础功能说明

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

1. 构建请求参数

1.1 使用示例

使用BUNativeExpressRewardedVideoAd构建广告请求

复制

1.2 接口说明

方法

说明

- (instancetype)initWithSlotID:(NSString *)slotID rewardedVideoModel:(BURewardedVideoModel *)model;

构建请求参数:

  • soltID:代码位ID ,必传
  • model:
    • rewardName:奖励名称,非必传
    • rewardAmount:奖励数量,非必传
    • extra:透传参数,非必传

2. 请求及展示广告

激励视频广告需要在广告播放完成给用户发放相应的奖励。接入方通过调用loadAdData请求广告,并在收到nativeExpressRewardedVideoAdDidDownLoadVideo回调后再调用showAdFromRootViewController方法展示激励视频广告,此处需要传入当前展示的页面。一定要设置rootViewController,即展示广告和跳转落地页需要的viewController

注意事项:

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

2.1 使用示例

复制

2.2 接口说明

  • BUNativeExpressRewardedVideoAd

方法

说明

- (void)loadAdData;

加载广告

- (BOOL)showAdFromRootViewController:(UIViewController *)rootViewController;

建议在收到nativeExpressRewardedVideoAdDidDownLoadVideo回调后展示广告

  • BUNativeExpressRewardedVideoAdDelegate

分类

方法

说明

广告加载回调

nativeExpressRewardedVideoAdDidLoad

广告素材物料加载成功

nativeExpressRewardedVideoAdDidDownLoadVideo

视频下载完成,建议在此回调方法中进行广告的展示操作,可保证播放流畅和展示流畅,用户体验更好。

nativeExpressRewardedVideoAd:didFailWithError

返回的错误码(error)说明详见链接。Link

广告渲染回调

nativeExpressRewardedVideoAdViewRenderSuccess

渲染成功回调。广告展示之后才会回调

nativeExpressRewardedVideoAdViewRenderFail:error

渲染失败,网络原因或者硬件原因导致渲染失败,可以更换手机或者网络环境测试。建议升级到穿山甲平台最新版本

广告交互回调

nativeExpressRewardedVideoAdWillVisible

模版激励视频广告即将展示

nativeExpressRewardedVideoAdDidVisible

模版激励视频广告已经展示

nativeExpressRewardedVideoAdWillClose

模版激励视频广告即将关闭

nativeExpressRewardedVideoAdDidClose

用户关闭广告时会触发此回调,建议开发者在用户观看完广告后在nativeExpressRewardedVideoAdDidClose回调里将原来的广告对象置为nil 保证广告对象为新的请求对象

nativeExpressRewardedVideoAdDidClick

点击回调方法

nativeExpressRewardedVideoAdDidClickSkip

跳过回调方法

nativeExpressRewardedVideoAdDidPlayFinish

视频正常播放完成时可触发此回调方法,当广告播放发生异常时,不会进入此回调;

nativeExpressRewardedVideoAdDidCloseOtherController:interactionType

此回调在广告跳转到其他控制器时,该控制器被关闭时调用interactionType:
此参数可区分是打开的appstore/网页/视频广告详情页面

奖励下发回调

nativeExpressRewardedVideoAdServerRewardDidSucceed

服务器奖励验证成功回调:开发者需要在此回调中进行奖励发放。详细说明请查看【高级功能说明-激励视频奖励下发说明】

nativeExpressRewardedVideoAdServerRewardDidFail:

服务器奖励验证失败回调:可在此回调方法中打印error,定位具体失败的原因,或通过抓包定位具体原因

四、高级功能说明

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

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

1.1 使用说明

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

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

方案二(优先级较高):在请求广告构建BUNativeExpressRewardedVideoAd时,使用BURewardedVideoModel,传入奖励名称与奖励数量。

  • 若奖励名称和数量任一为空,则认为此对值无效。
  • 奖励数量为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 客户端回调

穿山甲根据“奖励发放条件”,直接通过nativeExpressRewardedVideoAdServerRewardDidSucceed回调给到开发者客户端是否发放奖励,对接相对简单。

奖励验证回调涵盖目前所有激励视频播放异常的场景,包括非用户主动操作导致的视频无法完成播放。

接口说明

复制

2.2.2 服务端回调

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

五、资源

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


本篇目录
联系我们