Android iOS Unity JS API Media API 常见问题

激励广告

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

简介

基本信息

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

权限等级:开放

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

注意事项:如您正在使用模板2.0接口,请尽快按该文档更新接入方式,模板2.0接口将很快废弃,请尽快更新至4.12.80版本及以上。

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

竖屏广告 横屏广告

主要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

回调函数列表

回调函数名 回调函数含义
gdt_rewardVideoAdDidLoad 激励视频广告加载广告数据成功回调
gdt_rewardVideoAdVideoDidLoad 激励视频数据下载成功回调,已经下载过的视频会直接回调
gdt_rewardVideoAdWillVisible 激励视频播放页即将展示回调
gdt_rewardVideoAdDidExposed 激励视频广告曝光回调
gdt_rewardVideoAdDidClose 激励视频广告播放页关闭回调
gdt_rewardVideoAdDidClicked 激励视频广告信息点击回调
gdt_rewardVideoAd:didFailWithError 激励视频广告各种错误信息回调
gdt_rewardVideoAdDidRewardEffective 激励视频广告播放达到激励条件回调,以此回调作为奖励依据
gdt_rewardVideoAdDidPlayFinish 激励视频广告播放完成回调

接入代码示例

加载并显示激励广告

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

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
服务端回调说明

优量汇服务器会以 GET 方式请求第三方服务的回调链接,并拼接以下参数回传:

pid=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&sig=%s
字段定义 字段名称 字段类型 备注
pid 广告位ID string 签名
appid APP ID string
transid 交易id string 完成观看的唯一交易ID
userid 用户id string 调用SDK透传,应用对用户的唯一标识
extrainfo 其他信息 string 调用SDK传入并透传,如无需要则为空
sig 签名 string 签名

签名生成方式:

sig = sha256(transid:secret)

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

返回约定

返回 json 数据,字段如下:

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

回调URL格式示例如下:

{ 
   "isValid": true
}

如果回调URL没有正常返回,优量汇后台会重试两次,每次重试间隔200ms。

说明

  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回调,但广告还是展示异常,请录屏并反馈给技术支持人员。

Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇