开屏广告

一、集成建议

• 开屏广告是打开app的时候展示一个3-5s的全屏的广告
• 开屏广告分冷启动和热启动，冷启动时要尽可能提前开始加载广告，这样才能确保在进入app之前加载到并展示广告
• 热启动是app切换到后台，并没有真正的退出，这种情况下要能检测到并提前加载广告
• 开屏广告一般要配合app的启动页来使用，在加载的时间先给用户看启动页，等广告加载成功后展示广告，广告结束进入app内部

主要步骤

• 创建TradPlusAdSplash对象
• 加载开屏广告loadAdWithWindow:bottomView:
• 注册TradPlusADSplashDelegate 回调，获取广告加载、展示、点击、关闭等回调。
• 显示开屏广告showAdWithSceneId:

注意事项

• 不建议在tpSplashAdOneLayerLoad : didFailWithError:回调中执行广告加载的方法，对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑需要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。
• 不建议在tpSplashAdLoaded回调中直接执行广告展示的方法，这可能导致用户体验不佳，SDK有广告会过期自动补充功能和自动加载功能，加载成功后会回调tpSplashAdLoaded。开发者无法精准控制广告展示的时机。可配合产品逻辑在需要展示广告的地方，判断isAdReady是否有可用广告，再展示广告。
• 开发者需注意如果已经进入app内部，而加载时间过长,这次load结果就不应该展示了

二、TradPlusAdSplash API说明

1. 加载、展示广告

• 参数说明

参数	说明
adUnitID	adUnitID为TradPlus后台创建的广告位ID，SDK将根据广告位ID拉取配置并请求广告
window	广告展示时的window 注：确保展示时传入的window是keyWindow，否则可能会出现广告展示无效
bottomView	bottomView为半屏展示时底部自定义View，默认全屏展示时传nil 注：自定义view大小一般不超过屏幕的25%；支持广告平台为：Mintegral,腾讯广告，穿山甲，Sigmob，百度

• 方法说明

方法	说明
- (void)setAdUnitID:(NSString *)adUnitID;	设置广告位ID
- (void)loadAdWithWindow:(UIWindow *)window bottomView:(nullable UIView *)bottomView;	请求该广告位开屏广告
- (BOOL)isReady;	检测该广告位是否有可用广告 true为有可用广告 flase为无可用广告
- (void)entryAdScenario:(nullable NSString *)sceneId;	进入广告场景 广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数，所以请在准确的位置调用。
- (void)show;	展示该广告位开屏广告
- (void)showWithSceneId:(nullable NSString *)sceneId;	展示该广告位开屏广告 sceneId：场景ID，可以为nil

2. 监听回调

• 参数说明

参数	说明
adInfo	广告位ID、三方广告平台、ecpm等信息，具体请参考回调信息说明
error	返回的是TP封装的错误信息：详见： 错误码说明

• TradPlusADSplashDelegate 回调接口及说明

方法	说明
- (void)tpSplashAdLoaded:(NSDictionary *)adInfo;	开屏广告加载完成 v9.6.0+ 优化回调方式，一次loadAd对应一次tpSplashAdLoaded回调，不调用不回调。
- (void)tpSplashAdLoadFailWithError:(NSError *)error;	开屏广告加载失败，返回的是TP封装的错误信息。详见： 错误码说明 tpSplashAdOneLayerLoad:didFailWithError:返回三方源的错误信息
- (void)tpSplashAdImpression:(NSDictionary *)adInfo;	开屏广告展示成功，三方认可的有效展示
- (void)tpSplashAdShow:(NSDictionary *)adInfo didFailWithError:(NSError *)error;	开屏广告展示失败
- (void)tpSplashAdClicked:(NSDictionary *)adInfo;	开屏广告被点击
- (void)tpSplashAdDismissed:(NSDictionary *)adInfo;	开屏广告关闭

• TradPlusADSplashDelegate 回调接口及说明（可选）

方法	说明
- (void)tpSplashAdStartLoad:(NSDictionary *)adInfo;	v7.6.0+新增 开始加载流程
- (void)tpSplashAdLoadStart:(NSDictionary *)adInfo;	v7.6.0+已废弃 请使用tpSplashAdOneLayerStartLoad:
- (void)tpSplashAdOneLayerStartLoad:(NSDictionary *)adInfo;	当每个广告源开始加载时会都会回调一次。 v7.6.0+新增，替代原回调接口：tpSplashAdLoadStart:(NSDictionary *)adInfo;
- (void)tpSplashAdIsLoading:(NSDictionary *)adInfo;	v8.7.0+新增 调用load之后如果收到此回调，说明广告位仍处于加载状态，请等待上一轮load结果回调后再触发新的一轮广告加载。
- (void)tpSplashAdBidStart:(NSDictionary *)adInfo;	bidding开始
- (void)tpSplashAdBidEnd:(NSDictionary *)adInfo success:(BOOL)success;	v7.6.0+已废弃 请使用 tpSplashAdBidEnd:error:
- (void)tpSplashAdBidEnd:(NSDictionary *)adInfo error:(NSError *)error;	bidding结束 error = nil 表示成功
- (void)tpSplashAdOneLayerLoaded:(NSDictionary *)adInfo;	当每个广告源加载成功后会都会回调一次。
- (void)tpSplashAdOneLayerLoad:(NSDictionary *)adInfo didFailWithError:(NSError *)error;	当每个广告源加载失败后会都会回调一次，返回三方源的错误信息
- (void)tpSplashAdAllLoaded:(BOOL)success;	加载流程全部结束
- (void)tpSplashAdSkip:(NSDictionary *)adInfo;	v8.1.0+新增 跳过
- (void)tpSplashAdZoomOutViewShow:(NSDictionary *)adInfo;	v8.1.0+新增 点睛开始
- (void)tpSplashAdZoomOutViewClose:(NSDictionary *)adInfo;	v8.1.0+新增 点睛关闭

3.设置自定义原生模版

原生广告相关API及说明

• 参数说明

参数	说明
TPNativeTemplate	v8.4.0新增 指定原生开屏的渲染模版，未设置时SDK会使用默认模版进行渲染 customRenderingViewClass仅对Waterfall中的原生广告生效
TradPlusNativeRenderer	v8.4.0新增 指定原生开屏的renderer ，未设置时SDK会使用默认模版进行渲染 customRenderer仅对Waterfall中的原生广告生效
TPTemplateContentMode	设置原生开屏模版渲染的布局方式 TPTemplateContentModeCenter:保持在subview的center，默认 TPTemplateContentModeScaleToFill:自动充满subview
Size	模版渲染的尺寸大小

• 方法说明

方法	说明
- (void)setTemplateRenderSize:(CGSize)size;	设置原生开屏模版渲染的尺寸，需要在load之前设置 默认使用屏幕最短边正方形size进行渲染
- (void)showWithRenderingViewClass:(Class)renderingViewClass;	指定原生开屏的渲染模版展示广告
- (void)showWithRenderer:(TradPlusNativeRenderer *)renderer;	指定原生开屏的renderer展示广告

v8.4.0开始 开屏支持混用原生广告。对于需要使用自定义原生布局的开发者可以通过API来设置。

 //可通过此API设置原生的自定义模版，不设置时会使用默认模版
 // 指定原生开屏的渲染模版展示广告，renderingViewClass 仅对Waterfall中的原生广告生效
 [self.splashAd showWithRenderingViewClass:[TPNativeTemplate class]];
 
//自定义view方式
TPNativeTemplate *adView = [[NSBundle mainBundle] loadNibNamed:@"TPNativeTemplate" owner:self options:nil].lastObject;
adView.frame = [UIScreen mainScreen].bounds;
[adView layoutIfNeeded];
TradPlusNativeRenderer *nativeRenderer = [[TradPlusNativeRenderer alloc] init];
[nativeRenderer setTitleLable:adView.titleLabel canClick:YES];
[nativeRenderer setTextLable:adView.textLabel canClick:YES];
[nativeRenderer setCtaLable:adView.ctaLabel canClick:YES];
[nativeRenderer setIconView:adView.iconImageView canClick:YES];
[nativeRenderer setMainImageView:adView.mainImageView canClick:YES];
[nativeRenderer setAdChoiceImageView:adView.adChoiceImageView canClick:YES];
[nativeRenderer setAdView:adView canClick:YES];

//可通过此API设置原生的自定义Renderer，不设置时会使用默认模版
//指定原生开屏的renderer 展示广告，自定义renderer 仅对Waterfall中的原生广告生效
[self.splashAd showWithRenderer:nativeRenderer];

三、示例代码

请参考：TradPlusAdSplashViewController

#import <TradPlusAds/TradPlusAdSplash.h>

@interface TradPlusAdSplashViewController ()<TradPlusADSplashDelegate>
@property (nonatomic, strong) TradPlusAdSplash *splashAd;
@end

@implementation TradPlusAdSplashViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
	//初始化广告位
	self.splashAd = [[TradPlusAdSplash alloc] init];
	//设置广告位ID
	[self.splashAd setAdUnitID:@"在TP平台创建的广告位ID"];
	//设置代理
	self.splashAd.delegate = self;
	//加载广告并设置 window和自定义view 
	[self.splashAd loadAdWithWindow:[UIApplication sharedApplication].keyWindow bottomView:nil];
}

- (void)showsplashAd
{
   //调用isAdReady方法检查是否有可用广告，有可用广告时，调用show方法来展示广告
	if (self.splashAd.isAdReady)
	{
		[self.splashAd show];
	}
}

#pragma mark - TradPlusADSplashDelegate

//开屏广告加载完成
- (void)tpSplashAdLoaded:(NSDictionary *)adInfo
{
}
//开屏广告加载失败
- (void)tpSplashAdLoadFailWithError:(NSError *)error
{
}
//开屏广告展示成功 三方认可的有效展示
- (void)tpSplashAdImpression:(NSDictionary *)adInfo
{
}
//开屏广告展现失败
- (void)tpSplashAdShow:(NSDictionary *)adInfo didFailWithError:(NSError *)error
{
}
//开屏广告被点击
- (void)tpSplashAdClicked:(NSDictionary *)adInfo
{
}
//开屏广告关闭
- (void)tpSplashAdDismissed:(NSDictionary *)adInfo
{
}

四、广告平台特殊配置说明

Pangle（海外）

开发者可以通过一下代码设置Pangle（海外）开屏的 自定义icon（正方形）

v9.3.0及以上版本

UIImage *image = [UIImage imageNamed:@"icon"];
self.splashAd.localParams = @{@"pangleGlobal_appIcon":image};

五、开屏广告的推荐用法

应用启动方式

• 冷启动：当启动应用时，后台没有该应用的进程，这时系统会重新创建一个新的进程分配给该应用，这种方式叫“冷启动”
• 热启动：当启动应用时，后台已有该应用的进程，例：按home键推出再回到前台，或切换应用回到前台等，这种方式叫“热启动”

开屏加载策略

冷启动方式打开应用

• 第一时间在后台load广告，同时建议在loading页时最多停留5秒
  • 如果5秒内返回广告，直接显示。显示完后，再调用 load 方法加载一条广告，供下次热启动时使用
  • 如果5秒内未返回广告，则关闭loading页，直接进入应用主界面。如在此之后收到 loaded 回调，不要再调用show方法。本次广告不会丢弃，SDK会缓存下来备用
• 应用冷启动时，加载广告的过程中尽量不要同时请求其他网络资源，以免影响广告加载速度

热启动方式打开应用

• 有广告则直接显示
• 不管有无广告展示，都需要再加载一条新的广告，作为备用
• 如果应用能够监听到切换后台事件，可在切换后台时调用 isReady 方法判断广告是否Ready，如果没有Ready，可补充一条广告

开屏出现时机

推荐示例

在下面的推荐示例中，开屏广告在应用的加载屏幕上显示。

不推荐示例

如果用户已经进入应用Home页，则不要展示开屏广告。否则会突然弹出，容易造成用户误点击。