Bidding Android iOS Unity JS API Media API 常见问题

开屏广告

开屏广告包含两种广告形态:开屏 与 开屏V+ ,下面分别介绍两种广告形态的接入方案。

开屏广告

开屏广告简介

基本信息:开屏广告以App启动作为曝光时机,提供5s的可感知广告展示。用户可以点击广告跳转到目标页面;或者点击右上角的“跳过”按钮,跳转到app内容首页。

权限等级:开放

适用场景:开屏广告会在您的应用开启时加载,拥有固定展示时间(一般为5秒),展示完毕后自动关闭并进入您的应用主界面。
分类:开屏广告分为全屏和半屏,开屏全屏广告有更沉浸的广告播放体验,变现效果更佳。

全屏 半屏

奖励式开屏

奖励式开屏,是优量汇最新推出的广告形态。
奖励式开屏在原有交互基础上,开屏外层额外提示可「领惊喜奖励」,用户触发交互行为后,在落地页浏览满5秒,即可获得对应奖励。
(1)用户如感兴趣,在落地页浏览满5秒:开发者需针对满足浏览的用户,派发额外的奖励,如系统内的金币,生命值等。
(2)用户如不感兴趣,在落地页浏览未满5秒:可随时点击关闭按钮,退出广告。

接入效果:奖励式开屏,可增加开屏点击吸引力,提升该广告位eCPM和整体收益。

权限等级:请联系优量汇运营同学申请接入

备注说明:选中该样式时,您务必针对满足浏览的用户,派发额外奖励,如系统内的金币,生命值等。

支持版本:iOS SDK 4.13.70及以上

其他功能:当前样式同激励视频一样,支持奖励回调判断。

全屏 落地页

接入注意事项

  1. 开屏全屏广告需使得显示区域其高度与设备高度一致,即为开屏全屏广告。开发者可通过以下接口配合使用提供媒体logo,用以随开屏广告展示。
     - (void)loadFullScreenAd;
     - (void)showFullScreenAdInWindow:(UIWindow *)window withLogoImage:(UIImage *)logoImage skipView:(UIView *)skipView;
    
  2. 开屏半屏广告的显示区域其高度一定要大于设备高度的75%(建议值大于80%),最小高度要大于400dp,开屏广告默认只在竖屏展示,横屏一般不满足尺寸要求。
  3. 开屏广告支持回调广告展示的倒计时,开发者可以根据自己的需求设计倒计时 View 的样式,并可以决定什么时机显示倒计时。
  4. 开发者如果需要展示半开屏广告,即在开屏中保留部分区域显示其他信息,如 LOGO,可以参考 demo 设置其他单独的容器来展示该信息,但展示广告的容器请一定要满足注意事项3中描述的条件,否则影响曝光。
  5. 开屏广告接入 api 变化,原有方式将 SplashAD 的构造和广告的拉取展示耦合起来,新版 SDK 将广告的拉取和展示独立出来。因此需要开发者适配这一情况,调用 load 和 show 分别进行广告的拉取和展示。

主要API

生命周期事件回调

您可以实现全部或部分GDTSplashAdDelegate,以跟踪点击成功或者开屏广告请求失败等广告生命周期事件。

@protocol GDTSplashAdDelegate <NSObject>
@optional
- (void)splashAdSuccessPresentScreen;
- (void)splashAdFailToPresent:error;
- (void)splashAdApplicationWillEnterBackground;
- (void)splashAdExposured;
- (void)splashAdClicked;
- (void)splashAdWillClosed;
- (void)splashAdClosed;
- (void)splashAdWillPresentFullScreenModal;
- (void)splashAdDidPresentFullScreenModal;
- (void)splashAdWillDismissFullScreenModal;
- (void)splashAdDidDismissFullScreenModal;
- (void)splashAdLifeTime;
- (void)splashAdDidRewardEffective:info;
@end

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

Objective-C
self.splashAd.delegate = self;
Swift
splashAd.delegate = self

回调函数列表

回调函数名 回调函数含义
splashAdSuccessPresentScreen 开屏广告成功展示
splashAdFailToPresent 开屏广告展示失败
splashAdApplicationWillEnterBackground 当点击下载应用时会调用系统程序打开,应用切换到后台
splashAdExposured 开屏广告曝光回调
splashAdClicked 开屏广告点击回调
splashAdWillClosed 开屏广告将要关闭回调
splashAdClosed 开屏广告关闭回调
splashAdWillPresentFullScreenModal 开屏广告点击以后即将弹出全屏广告页
splashAdDidPresentFullScreenModal 开屏广告点击以后弹出全屏广告页
splashAdWillDismissFullScreenModal 点击以后全屏广告页将要关闭
splashAdDidDismissFullScreenModal 点击以后全屏广告页已经关闭
splashAdLifeTime 开屏广告剩余时间回调
splashAdDidRewardEffective 奖励式开屏广告,浏览落地页达到激励条件时触发的回调

多阶底价能力

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

step1:

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

step2:

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

/**
 返回广告的eCPM等级

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

实时竞价能力

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

step1:

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

step2:

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

/**
 返回广告的eCPM,单位:分

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

说明

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

接入代码示例

加载并显示开屏广告

1.在AppDelegate头文件中导入头文件并声明实例

Objective-C
 #import "GDTSplashAd.h"
 @interface GDTAppDelegate : UIResponder <UIApplicationDelegate,GDTSplashAdDelegate>
 @property (strong, nonatomic) GDTSplashAd *splash;
 @property (retain, nonatomic) UIView *bottomView;
 @end
Swift
class SplashViewController: UIViewController,GDTSplashAdDelegate {
    private var splashAd: GDTSplashAd!
    private var bottomView: UIView!
    ...
  }

2.在AppDelegate的实现文件中初始化并加载广告数据,开屏广告目前支持全屏开屏和半屏开屏广告两种形式,其中半屏开屏广告支持开发者自定义设置开屏底部的界面,用以展示应用Logo等。

/**
 *  发起拉取全屏广告请求,只拉取不展示
 *  详解:广告素材及广告图片拉取成功后会回调splashAdDidLoad方法,当拉取失败时会回调splashAdFailToPresent方法
 */
- (void)loadFullScreenAd;

/**
 *  展示全屏广告,调用此方法前需调用isAdValid方法判断广告素材是否有效
 *  详解:广告展示成功时会回调splashAdSuccessPresentScreen方法,展示失败时会回调splashAdFailToPresent方法
 */
- (void)showFullScreenAdInWindow:(UIWindow *)window withLogoImage:(UIImage *)logoImage skipView:(UIView *)skipView;

 /**
 *  发起拉取广告请求,只拉取不展示
 *  详解:广告素材及广告图片拉取成功后会回调splashAdDidLoad方法,当拉取失败时会回调splashAdFailToPresent方法
 */
- (void)loadAd;

/**
 *  展示广告,调用此方法前需调用isAdValid方法判断广告素材是否有效
 *  详解:广告展示成功时会回调splashAdSuccessPresentScreen方法,展示失败时会回调splashAdFailToPresent方法
 */
- (void)showAdInWindow:(UIWindow *)window withBottomView:(UIView *)bottomView skipView:(UIView *)skipView;

/**
 * 返回广告是否可展示
 * 对于并行请求,在调用showAdInWindow前时需判断下
 * @return 当广告已经加载完成&&未曝光&&未过期时,为YES,否则为NO
 */
- (BOOL)isAdValid;
Objective-C
  // splash LoadAd 逻辑
  GDTSplashAd *splash = [[GDTSplashAd alloc] initWithPlacementId:YOUR_PLACEMENT_ID];
  splash.delegate = self; //设置代理
  //根据iPhone设备不同设置不同背景图
  if ([[UIScreen mainScreen] bounds].size.height >= 568.0f) {
   splash.backgroundColor = [UIColor colorWithPatternImage:[UIImage imageNamed:@"LaunchImage-568h"]];
  } else {
   splash.backgroundColor = [UIColor colorWithPatternImage:[UIImage imageNamed:@"LaunchImage"]];
  }
  splash.fetchDelay = 3; //开发者可以设置开屏拉取时间,超时则放弃展示
  [splashAd loadFullScreenAd];

  ......

  // splash show逻辑
  //设置开屏自定义 logo,展示半屏开屏广告
  UIWindow *window = [[UIApplication sharedApplication] keyWindow];
  [self.splashAd showFullScreenAdInWindow:window withLogoImage:[UIImage imageNamed:@"SplashLogo"] skipView:nil];
Swift
  // splash LoadAd 逻辑
  splashAd = GDTSplashAd.init(placementId: YOUR_PLACEMENT_ID)
  splashAd.delegate = self
  splashAd.fetchDelay = 3
  var splashImage = UIImage.init(named: "SplashNormal")
  if Util.isIphoneX() {
      splashImage = UIImage.init(named: "SplashX")
  } else if Util.isSmallIphone() {
      splashImage = UIImage.init(named: "SplashSmall")
  }
  splashAd.backgroundImage = splashImage
  self.splashAd.load()

  // splash show逻辑
  bottomView = UIView.init(frame: CGRect(origin: CGPoint.zero, size: CGSize(width: UIScreen.main.bounds.size.width, height: UIScreen.main.bounds.height * 0.25)))
  bottomView.backgroundColor = .white
  let logo = UIImageView.init(image: UIImage.init(named: "SplashLogo"))
  logo.frame = CGRect(origin: CGPoint.zero, size: CGSize(width: 311, height: 47))
  logo.center = bottomView.center
  bottomView.addSubview(logo)
  let window = UIApplication.shared.keyWindow
  splashAd.show(in: window, withBottomView:  bottomView, skip: nil)

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

说明

目前开屏广告只针对iPhone设备在垂直方向上展示。
广告发起请求并展示在Window中,同时在屏幕底部设置应用自身的Logo页面或是自定义View,Logo页面或是自定义View所占的空间不能过大,高度不能超过屏幕高度的 25%。

设置自定义跳过按钮

您可以设置自定义跳过按钮,可以通过设置skipView的frame来修改自定义按钮的位置及大小。

Objective-C
UIView *customSkipView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 100, 50)]; // 设置跳过按钮的frame信息
UIWindow *window = [[UIApplication sharedApplication] keyWindow];
[self.splashAd showAdInWindow:window withBottomView:self.bottomView skipView:customSkipView];
Swift
let customView = UIView.init(frame: CGRect(x: 0,y: 0,width: 100,height: 50)) // 设置跳过按钮的frame信息
let window = UIApplication.shared.keyWindow
self.splashAd.show(in: window, withBottomView:  bottomView, skip: customView)

开屏广告拉取超时时间

您可以设置拉取广告的超时时间,默认为3秒。通常情况,开发者调用loadAd后开始计时,如果在该时间内广告拉取成功,则返回成功回调;否则返回超时回调。

Objective-C
self.splashAd.fetchDelay = 5;
Swift
splashAd.fetchDelay = 5

在不展示开屏广告时执行调试

在您的ViewController里实现如下回调,处理开屏广告加载失败的问题:

Objective-C
- (void)splashAdFailToPresent:(GDTSplashAd *)splashAd 
withError:(NSError *)error
{
    NSLog(@"%s%@",__FUNCTION__,error);
}
Swift
func splashAdFail(toPresent splashAd: GDTSplashAd!, withError error: Error!) {
    print(#function,error)
}

说明:开屏广告只支持竖屏使用。

奖励发放机制

回调时机说明

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

服务端验证说明

当选择需要服务端验证时,开发者需要按照以下要求进行接口开发,并在平台上填写回调URL。
服务端回调是指在用户看完激励视频达到奖励条件时,优量汇服务端会向开发者服务端发送一个验证请求,同时客户端会给出splashAdDidRewardEffective: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。

预加载开屏广告

优量汇开屏广告支持预加载开屏广告,调用方法如下:

    GDTSplashAd *preloadSplashAd = [[GDTSplashAd alloc] initWithPlacementId:YOUR_PLACEMENT_ID];
    [preloadSplashAd preloadSplashOrderWithPlacementId:YOUR_PLACEMENT_ID];

说明:将YOUR_PLACEMENT_ID替换成你自己的PLACEMENTID。

开屏V+广告

开屏V+广告简介

基本信息:开屏V+广告:5s-30s的视频广告,在5s开屏呈现的过程中用户点击右上角的“进入首页”或5s曝光结束后视频将收缩到APP内右下角的小视窗继续播放。

权限等级:需申请

适用场景:开屏V+广告会在您的应用开启时加载,广告曝光过程中用户点击右上角的“进入首页”或5s曝光结束后将收缩到APP首页右下角的小视窗继续播放。

分类:开屏V+广告分为半屏和全屏,其中半屏开屏V+广告支持开发者自定义设置开屏底部的界面,用以展示应用Logo等。具体种类可以在开发者平台进行选择:

全屏 半屏 App首页 落地页
视频示例

主要API

生命周期事件回调

您可以实现全部或部分GDTSplashZoomOutViewDelegate,以跟踪点击成功或者开屏V+广告请求失败等广告生命周期事件。

@protocol GDTSplashZoomOutViewDelegate <NSObject>
- (void)splashZoomOutViewDidClick:(GDTSplashZoomOutView *)splashZoomOutView;
- (void)splashZoomOutViewAdDidClose:(GDTSplashZoomOutView *)splashZoomOutView;
- (void)splashZoomOutViewAdVideoFinished:(GDTSplashZoomOutView *)splashZoomOutView;
- (void)splashZoomOutViewAdDidPresentFullScreenModal:(GDTSplashZoomOutView *)splashZoomOutView;
- (void)splashZoomOutViewAdDidDismissFullScreenModal:(GDTSplashZoomOutView *)splashZoomOutView;
@end

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

Objective-C
self.splashAd.delegate = self;
Swift
splashAd.delegate = self

回调函数列表

回调函数名 回调函数含义
splashZoomOutViewDidClick 开屏V+广告被点击
splashZoomOutViewAdDidClose 开屏V+广告关闭
splashZoomOutViewAdVideoFinished 开屏V+广告视频播放完成
splashZoomOutViewAdDidPresentFullScreenModal 开屏V+广告进入视频详情页
splashZoomOutViewAdDidDismissFullScreenModal 开屏V+广告退出视频详情页

开屏V+接入代码示例

加载并显示开屏V+广告

Objective-C
  // splash LoadAd 逻辑
  ......
  splashAd.needZoomOut = YES; //开发者可以选择使用开屏V+
  [splashAd loadAd];
  ......
Swift
  // splash LoadAd 逻辑
  ......
  splashAd.needZoomOut = TRUE //开发者可以选择使用开屏V+
  self.splashAd.load()
  ......

命中开屏V+后的操作

如果命中开屏V+,会在splashDidLoad回调中的splashAd的splashZoomOutView上得到体现。需要手动将开屏V+视图加到首页中,且设置rootViewController属性。

- (void)splashAdDidLoad:(GDTSplashAd *)splashAd {
    if (splashAd.splashZoomOutView) {
        [self.view addSubview:splashAd.splashZoomOutView]; // 将开屏V+视图加到首屏中
        splashAd.splashZoomOutView.rootViewController = self; // 设置开屏V+的rootViewController
        [splashAd.splashZoomOutView supportDrag]; // 如果想让开屏V+支持拖拽,需要引入优量汇开源类头文件"GDTSplashZoomOutView+GDTDraggable.h",并进行设置
    }
}

说明

拖拽功能作为开源类提供到了GDTSplashZoomOutView+GDTDraggable.hGDTSplashZoomOutView+GDTDraggable.m中,支持流量根据自己需要选用或修改。

开屏闪挂默认在App右侧,流量可以通过修改splashAd.splashZoomOutView的frame。推荐尺寸为9:16。
如果需要拖动功能,请去优量汇开发者平台官网下载最新版Sample Demo项目,获取GDTSplashZoomOutView+GDTDraggable.hGDTSplashZoomOutView+GDTDraggable.m文件

预加载开屏V+广告

优量汇开屏广告支持预加载开屏V+广告,调用方法如下:

    GDTSplashAd *preloadSplashAd = [[GDTSplashAd alloc] initWithPlacementId:YOUR_PLACEMENT_ID];
    preloadSplashAd.needZoomOut = YES;
    [preloadSplashAd preloadSplashOrderWithPlacementId:YOUR_PLACEMENT_ID];

说明:将YOUR_PLACEMENT_ID替换成你自己的PLACEMENTID

屏蔽摇一摇广告

开发者可以通过此接口,在广告请求维度关闭开屏广告摇一摇能力。

接口说明

支持的配置项 值类型 说明
shakable 字符串 "0":屏蔽开屏摇一摇广告
"1"或不传: 不屏蔽开屏摇一摇广告
#import "GDTSDKConfig.h"

+ (void)setExtraUserData:(NSDictionary <NSString *, NSString *> *)extraUserDictionary;

接入代码示例

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //...
    [GDTSDKConfig registerAppId:kGDTMobSDKAppId];
    [GDTSDKConfig setExtraUserData:@{@"shakable":@"0"}]; // 屏蔽开屏摇一摇广告
    return YES;
}

 文档反馈

腾讯公司 版权所有