激励广告

激励广告接入方式参考下方内容。

简介

基本信息

激励视频广告是指将短视频融入到app场景当中，成为app“任务”之一，用户观看短视频广告后可以得到一些应用内奖励。

权限等级：开放

适用场景：常见于游戏内的广告样式，多出现在游戏的复活、登录等位置，或者网服类app的一些增值服务场景。建议开发者在分析媒体属性和功能的基础上，判断是否嵌入。

分类：广告样式有横版竖版之分，您可以根据播放的场景创建对应屏幕方向的广告位。样式图如下：

竖屏广告	横屏广告

主要API

激励视频广告生命周期事件回调

您可以实现全部或部分GDTRewardedVideoAdDelegate，以跟踪点击成功或者激励视频广告请求失败等广告生命周期事件。

@protocol GDTRewardedVideoAdDelegate <NSObject>
@optional
- (void)gdt_rewardVideoAdDidLoad:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAdVideoDidLoad:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAdWillVisible:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAdDidExposed:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAdDidClose:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAdDidClicked:(GDTRewardVideoAd *)rewardedVideoAd;
- (void)gdt_rewardVideoAd:(GDTRewardVideoAd *)rewardedVideoAd didFailWithError:(NSError *)error;
- (void)gdt_rewardVideoAdDidRewardEffective:(GDTRewardVideoAd *)rewardedVideoAd info:(NSDictionary *)info;
- (void)gdt_rewardVideoAdDidPlayFinish:(GDTRewardVideoAd *)rewardedVideoAd;
@end

在实现上述事件回调之前，请务必先设置delegate:

Objective-C

self.rewardVideoAd.delegate = self;

Swift

rewardVideoAd.delegate = self

回调函数列表

接入代码示例

加载并显示激励广告

请勿使用模板激励视频广告位调用原生激励视频的接口，否则不会返回广告!!!

1.在控制器头文件中加入SDK头文件，声明rewardVideoAd属性

Objective-C

 #import "GDTRewardVideoAd.h"
 @interface RewardVideoViewController ()<GDTRewardedVideoAdDelegate>
 @property (nonatomic, strong) GDTRewardVideo *rewardVideoAd;

Swift

  class RewardVideoViewController: UIViewController,GDTRewardedVideoAdDelegate {
  var rewardVideoAd:GDTRewardVideo!
  ...
}

2.在ViewController的实现文件中初始化并加载广告数据：

Objective-C

 - (void)viewDidLoad
 {
     [super viewDidLoad];
     self.rewardVideoAd = [[GDTRewardVideo alloc] initWithPlacementId:@"YOUR_PLACEMENT_ID"];
     self.rewardVideoAd.delegate = self;
     self.rewardVideoAd.videoMuted = NO; // 设置激励视频是否静音
     [self.rewardVideoAd loadAd];
 }

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    self.rewardVideoAd = GDTRewardVideoAd.init(placementId: YOUR_PLACEMENT_ID)
    self.rewardVideoAd.delegate = self
    self.rewardVideoAd.videoMuted = false // 设置激励视频是否静音
    self.rewardVideoAd.load()
}

3.将YOUR_PLACEMENT_ID替换成你自己PLACEMENTID。

4.展示激励视频广告前必须先调用isAdValid判断广告是否有效，建议您在gdt_rewardVideoAdVideoDidLoad回调之后再做激励视频的展示：

Objective-C

- (void)gdt_rewardVideoAdVideoDidLoad:(GDTRewardVideoAd *)rewardedVideoAd
{
    NSLog(@"视频文件加载成功");
    self.isVideoLoaded = YES;
}
// 确认激励视频广告有效性之后，在合适的时机展示广告
- (IBAction)playVideo:(UIButton *)sender {
    if (!self.isVideoLoaded) {
         return;
    }
    if (!self.rewardVideoAd.isAdValid) {
        self.statusLabel.text = @"广告失效，请重新拉取";
        return;
    }

    [self.rewardVideoAd showAdFromRootViewController:self];

}

Swift

func gdt_rewardVideoAdVideoDidLoad(_ rewardedVideoAd: GDTRewardVideoAd!) {
    print(@"视频文件加载成功")
}
// 确认激励视频广告有效性之后，在合适的时机展示广告
@IBAction func clickPlay(_ sender: Any) {
  if (self.rewardVideoAd.expiredTimestamp <= Int(Date.init().timeIntervalSince1970)) {
    self.statusLabel.text = "广告已过期，请重新拉取"
    return
  }
  if (!self.rewardVideoAd.isAdValid) {
    self.statusLabel.text = "广告失效，请重新拉取"
    return
  }
  self.rewardVideoAd.show(fromRootViewController: self)
}

在不展示激励视频广告时执行调试

在您的ViewController里实现如下回调，处理激励视频广告加载失败的问题：

Objective-C

- (void)gdt_rewardVideoAd:(GDTRewardVideoAd *)rewardedVideoAd didFailWithError:(NSError *)error
{
    if (error.code == 4014) {
        NSLog(@"请拉取到广告后再调用展示接口");
        self.statusLabel.text = @"请拉取到广告后再调用展示接口";
    } else if (error.code == 4016) {
        NSLog(@"应用方向与广告位支持方向不一致");
        self.statusLabel.text = @"应用方向与广告位支持方向不一致";
    } else if (error.code == 5012) {
        NSLog(@"广告已过期");
        self.statusLabel.text = @"广告已过期";
    } else if (error.code == 4015) {
        NSLog(@"广告已经播放过，请重新拉取");
        self.statusLabel.text = @"广告已经播放过，请重新拉取";
    } else if (error.code == 5002) {
        NSLog(@"视频下载失败");
        self.statusLabel.text = @"视频下载失败";
    } else if (error.code == 5003) {
        NSLog(@"视频播放失败");
        self.statusLabel.text = @"视频播放失败";
    } else if (error.code == 5004) {
        NSLog(@"没有合适的广告");
        self.statusLabel.text = @"没有合适的广告";
    }
    NSLog(@"ERROR: %@", error);
}

Swift

func gdt_rewardVideoAd(_ rewardedVideoAd: GDTRewardVideoAd!, didFailWithError error: Error!) {
    let code = (error as NSError).code
    if (code == 4014) {
        print("请拉取到广告后再调用展示接口")
        self.statusLabel.text = "请拉取到广告后再调用展示接口"
    } else if (code == 5012) {
        print("广告已过期")
        self.statusLabel.text = "广告已过期"
    } else if (code == 4015) {
        print("广告已经播放过，请重新拉取")
        self.statusLabel.text = "广告已经播放过，请重新拉取"
    } else if (code == 5002) {
        print("视频下载失败")
        self.statusLabel.text = "视频下载失败"
    } else if (code == 5003) {
        print("视频播放失败")
        self.statusLabel.text = "视频播放失败"
    } else if (code == 5004) {
        print("没有合适的广告");
        self.statusLabel.text = "没有合适的广告"
    }
    print("\(error)")
}

多阶底价能力

接入多阶底价能力分2步：

step1:

找优量汇运营同学开通广告位的多阶底价权限并提供底价配置信息；

step2:

当广告拉取成功后，通过GDTRewardVideoAd类的eCPMLevel属性查看当前激励视频广告对应的底价层级。

/**
 返回广告的eCPM等级

 @return 成功返回一个包含数字的string，比如@"2"表示底价等级为2，@""或nil表示无权限或后台异常
 */
@property (nonatomic, readonly) NSString *eCPMLevel;

实时竞价能力

接入实时竞价能力分2步：

step1:

找优量汇运营同学开通广告位的实时竞价权限；

step2:

当广告拉取成功后，通过GDTRewardVideoAd类的eCPM属性获取本条广告实时的eCPM价格，单位是分。

/**
 返回广告的eCPM，单位：分

 @return 成功返回一个大于等于0的值，-1表示无权限或后台出现异常
 */
- (NSInteger)eCPM;

说明：

当无权限调用该接口时，SDK会返回错误码-1。

奖励发放机制

回调时机说明

gdt_rewardVideoAdDidRewardEffective:info:
在满足激励条件时会触发此回调，与是否选择服务端验证以及服务端验证是否成功无关。若选择了服务端验证，可以通过info中的GDT_TRANS_ID键获取此次交易的transId.

服务端验证说明

当选择需要服务端验证时，开发者需要按照以下要求进行接口开发，并在平台上填写回调URL。
服务端回调是指在用户看完激励视频达到奖励条件时，优量汇服务端会向开发者服务端发送一个验证请求，同时客户端会给出gdt_rewardVideoAdDidRewardEffective:info:回调，开发者根据回调进行奖励发放，因为奖励回调和服务端验证请求是同时发送的，开发者后台收到验证请求可能会有延迟或网络原因上的失败，开发者需要平衡用户体验与奖励验证。

开发者可以设置serverSideVerificationOptions属性来设置需要透传的参数

@interface GDTServerSideVerificationOptions : NSObject

//用户的userid,可选
@property(nonatomic, copy, nullable) NSString *userIdentifier;

//服务器端验证回调中包含的可选自定义奖励字符串
@property(nonatomic, copy, nullable) NSString *customRewardString;

@end

具体示例：

Objective-C

//如果设置了服务端验证，可以设置serverSideVerificationOptions属性
    GDTServerSideVerificationOptions *ssv = [[GDTServerSideVerificationOptions alloc] init];
    ssv.userIdentifier = @"APP's user id for server verify";
    ssv.customRewardString = @"APP's custom data";
    self.rewardVideoAd.serverSideVerificationOptions = ssv;

Swift

//如果设置了服务端验证，可以设置serverSideVerificationOptions属性
let ssv = GDTServerSideVerificationOptions()
ssv.userIdentifier = "APP's user id for server verify"
ssv.customRewardString = "APP's custom data"
self.rewardVideoAd.serverSideVerificationOptions = ssv

服务端回调说明

优量汇服务器会以GET方式请求您在开发者平台上注册的服务器回调链接，并拼接以下参数进行回传：

pid=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&sig=%s

具体示例：

https://sdk.e.qq.com/s2s?placementId=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&Fsig=%s

补充：
优量汇后台向上述URL发起请求后，您会在服务端收到某个transid的请求，如果签名验证正确，那么此transid对应的曝光为有效曝光
如果拼接的回调URL无法正常请求您的服务端，优量汇后台会进行两次重试，每次重试间隔200ms

签名生成方式：

sig = sha256(transid:secret)

其中transid为交易id，secret为您在优量汇媒体平台输入服务端URL时获取到的密钥。

说明：

1. 建议在释放激励视频广告 GDTRewardVideoAd 对象之前将 GDTRewardVideoAd 对象的 delegate 属性设置为nil.
2. 当用户点击广告弹出内置目标页时，请勿释放 GDTRewardVideoAd 实例。
3. 广告从拉取成功会提供 expiredTimestamp 属性表示广告的超时时间，展示广告之前请做广告的有效性检查，广告如果失效请提前重新拉取，否则将作无法展示广告。
4. 如果想设置激励视频广告是否静音，可以通过设置属性videoMuted。注意，不支持在激励视频展示期间修改videoMuted的值。

激励视频问题排查流程：

1. 首先确认是否已拉取到广告，即是否有收到gdt_rewardVideoAdDidLoad回调，若未收到，请根据gdt_rewardVideoAd:didFailWithError中的error.code查询失败原因；
2. 若拉取广告成功，但展示广告失败，请根据gdt_rewardVideoAd:didFailWithError中的error查询失败原因，并检查代码确认是否在gdt_rewardVideoAdVideoDidLoad回调后调用的showAdFromRootViewController方法；
3. 若拉取广告成功，且在gdt_rewardVideoAdVideoDidLoad回调后调用的showAdFromRootViewController方法，也未收到gdt_rewardVideoAd:didFailWithError回调，但广告还是展示异常，请录屏并反馈给技术支持人员。