开屏广告

开屏广告包含两种广告形态：开屏 与 开屏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. 开发者如果需要展示半开屏广告，即在开屏中保留部分区域显示其他信息，如 LOGO，可以参考 demo 设置其他单独的容器来展示该信息，但展示广告的容器请一定要满足注意事项3中描述的条件，否则影响曝光。
4. 开屏广告接入 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

回调函数列表

多阶底价能力

接入多阶底价能力分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

具体示例：

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时获取到的密钥。

预加载开屏广告

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

    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

回调函数列表

开屏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.h和GDTSplashZoomOutView+GDTDraggable.m中，支持流量根据自己需要选用或修改。

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

预加载开屏V+广告

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

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

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

屏蔽摇一摇广告

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

接口说明

#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;
}