中文
登录
后可查看全部文档
开发测试/iOS集成文档/开屏广告
开屏广告
最近更新 2024-08-02 11:17:01

简介

开屏广告主要是 APP 启动时展示的全屏广告视图,开发只要按照接入标准就能够展示设计好的视图。展示完毕后自动关闭并进入应用的主界面。为提高开发者的收入体验,穿山甲4700版本上线新版开屏广告降低开发者的接入成本。

新版开屏广告使用BUSplashAd对象管理开屏广告所有业务。开屏广告所有视图的展示和移除将由SDK统一管理,开发者无需关心。

接入方式上,使用BUSplashAd对象调用loadAdData方法请求广告,调用show方法展示广告,通过设置BUSplashAdDelegate代理,获取广告加载、 渲染、点击、关闭、跳转等回调。

重大变化

接口删除&新增

为提高开发者的收入及接入体验,4700版本开始,开发者需重新接入开屏功能,否则将无法成功请求开屏广告。

  • 不再使用视图对象接入,不区分自渲染接入和模板渲染接入,使用BUSplashAd对象加载和展示广告
  • 删除了旧版 BUNativeExpressSplashView
  • 删除了 旧版 BUSplashAdView
  • 新增了BUSplashAd类,用来加载和展示广告

新接口(BUSplashAd)预览[V4700+]

属性

说明

@property (nonatomic, weak, nullable) id<BUSplashAdDelegate> delegate;

开屏相关代理

@property (nonatomic, weak, nullable) id<BUSplashZoomOutDelegate> zoomOutDelegate;

开屏点睛相关代理

@property (nonatomic, assign) BOOL supportZoomOutView;

是否支持点睛

@property (nonatomic, assign) BOOL supportCardView;

是否支持卡片

@property (nonatomic, assign) BOOL hideSkipButton;

是否隐藏跳过按钮

@property (nonatomic, assign) NSTimeInterval tolerateTimeout;

广告加载超时时间

@property (nonatomic, copy, readonly, nonnull) NSString *slotID;

slotID

mediaExt@property (nonatomic, copy, readonly) NSDictionary *mediaExt;

mediaExt

@property (nonatomic, weak, readonly, nullable) UIViewController *splashRootViewController;

开屏视图控制器

@property (nonatomic, strong, readonly, nullable) BUSplashView *splashView;

开屏视图

@property (nonatomic, strong, readonly, nullable) BUSplashCardView *cardView;

卡片视图

@property (nonatomic, strong, readonly, nullable) BUSplashZoomOutView *zoomOutView;

点睛视图

@property (nonatomic, strong, readonly, nullable) UIView *splashViewSnapshot;

开屏最后一帧


方法

说明

- (instancetype)initWithSlotID:(NSString *)slotID adSize:(CGSize)adSize;

初始化方法

- (instancetype)initWithSlot:(BUAdSlot *)slot adSize:(CGSize)adSize;

初始化方法

- (void)loadAdData;

加载广告

- (void)showSplashViewInRootViewController:(UIViewController *)viewController;

展示开屏视图

- (void)showCardViewInRootViewController:(UIViewController *)viewController;

展示开屏联动卡片视图

- (void)showZoomOutViewInRootViewController:(UIViewController *)viewController;

展示开屏点睛视图

- (void)removeSplashView;

自定义跳过按钮场景,移除开屏视图

- (NSString *)getAdCreativeToken;


旧接口(BUSplashAdView)预览[V<4700]

属性

说明

@property (nonatomic, weak, nullable) id<BUSplashAdDelegate> delegate;

开屏相关代理

@property (nonatomic, getter=isAdValid, readonly) BOOL adValid;

是否展示

@property (nonatomic, assign) BOOL needSplashZoomOutAd;

是否支持点睛;3600版本开始,开发者不需要设置此方法,是否展示点睛样式通过穿山甲平台进行设置。

@property (nonatomic, assign) BOOL hideSkipButton;

是否隐藏跳过按钮

@property (nonatomic, assign) NSTimeInterval tolerateTimeout;

广告加载超时时间

@property (nonatomic, copy, readonly, nonnull) NSString *slotID;

slotID

mediaExt@property (nonatomic, copy, readonly) NSDictionary *mediaExt;

mediaExt

@property (nonatomic, strong, readonly, nullable) BUSplashZoomOutView *zoomOutView;

点睛视图


方法

说明

- (instancetype)initWithSlotID:(NSString *)slotID frame:(CGRect)frame;

初始化方法

- (instancetype)initWithSlot:(BUAdSlot *)slot adSize:(CGSize)adSize;

初始化方法

- (void)loadAdData;

加载广告

- (void)removeSplashView;

自定义跳过按钮场景,移除开屏视图

- (NSString *)getAdCreativeToken;


开屏接入-新接口概览[V4700+]

创建广告位对象、请求广告、展示广告

广告位对象创建时必须传入广告位ID:

复制

广告物料、素材加载成功后,会回调splashAdLoadSuccess:方法,在这里调用show方法展示广告:

方式一(推荐):

使用App主window对象的根视图控制器展示,不需要管理开屏控制器展示、关闭等操作:

(参考demo BUDSplashViewController 类)

复制

方式二:

使用新创建的视图控制器接入,需要自己管理viewController的展示和关闭:

(参考demo BUDSplashContainerViewController 类)

复制

开屏相关代理回调中关闭当前视图控制器:

复制

超时时长设置

超时的计算逻辑:穿山甲从开发者加载广告开始倒计时(注意并非从SDK初始化开始计时),若广告在倒计时结束之前完成广告加载,则会为开发者响应广告。若倒计时结束前未完成广告加载,则将响应超时。建议开发者:

复制

自定义跳过按钮

SDK支持开发者自定义跳过按钮, 通过设置hideSkipButton属性,控制SDK内跳过按钮隐藏:

复制

在广告渲染成功回调中,获取渲染好的splashView添加自定义按钮(此时splashview还没有展示,不用担心添加视图的闪烁问题) :

复制

需要自己处理跳过按钮事件,在点击事件中实现关闭开屏视图,可以使用SDK提供的removeSplashView方法移除开屏视图:

复制

自定义底部logo设置

开发者可自定义开屏底部View,用于logo展示等个性化设置。

复制

开屏回调说明

时机

方法

说明

广告物料、素材加载成功


- (void)splashAdLoadSuccess:(BUSplashAd *)splashAd;


物料加载成功,可以在这个回调中调用show方法展示开屏

广告物料、素材加载失败

- (void)splashAdLoadFail:(BUSplashAd *)splashAd error:(BUAdError *)error;


物料加载失败,不会展示开屏,提供如下错误码:

typedef NS_ENUM(NSInteger, BUSplashAdLoadError) {

BUSplashAdLoadError_UnKnow= 0, //未知错误

BUSplashAdLoadError_DataError = 1, // 数据加载失败

BUSplashAdLoadError_TimeOut = 2, // 超时

};

广告渲染成功

- (void)splashAdRenderSuccess:(BUSplashAd *)splashAd;

load方法调用后,若渲染成功则返回该回调;show方法调用后开屏视图会被添加到ViewController上。

广告渲染失败

- (void)splashAdRenderFail:(BUSplashAd *)splashAd error:(BUAdError *)error;


load方法调用后,若渲染失败则返回该回调;即使调用show方法开屏视图也不会被添加到ViewController上,提供如下错误码:

typedef NS_ENUM(NSInteger, BUSplashAdErrorCode) { CSJSplashAdError_Unknow = 0, CSJSplashAdError_LoadFailed = 1, // 物料加载失败 CSJSplashAdError_ResourceFailed = 2, // 素材加载失败 CSJSplashAdError_RenderFailed = 3, // 渲染失败 CSJSplashAdError_TimeOut = 23 // 超时

};

广告即将展示

- (void)splashAdWillShow:(BUSplashAd * )splashAd;


广告展示

- (void)splashAdDidShow:(BUSplashAd * )splashAd;

注意:该回调时机和show埋点上报时机一致

广告视图关闭


- (void)splashAdDidClose:(BUSplashAd * )splashAd closeType:(BUSplashAdCloseType)closeType;



广告视图会在以下场景关闭:

1、开屏未转化关闭(点击跳过、倒计时结束),通知开发者开屏视图已经关闭

2、 开屏转化后内开调起市场页,市场页关闭时通知开发者开屏视图已经关闭

3、开屏转化其他场景,点击广告后通知开发者开屏视图已经关闭

其他说明:

1、广告视图关闭后由SDK移除开屏视图

2、closeType标记从哪种场景关闭

复制

广告视图控制器关闭



- (void)splashAdViewControllerDidClose:(BUSplashAd *)splashAd;


如果采用自定义视图控制器展示广告,广告视图控制器会在以下场景关闭:

1、开屏未转化关闭(点击跳过、倒计时结束),通知开发者关闭视图控制器

2、开屏转化后内跳,中间页、市场页关闭时,通知开发者关闭视图控制器

3、开屏转化外跳,即将跳转时,通知开发者关闭视图控制器

广告点击

- (void)splashAdDidClick:(BUSplashAd * )splashAd;


广告中间页、市场页面关闭

- (void)splashDidCloseOtherController:(BUSplashAd *)splashAd interactionType:(BUInteractionType)interactionType;


此回调在广告跳转到其他控制器时,该控制器被关闭时调用。

interactionType:此参数可区分是打开的appstore/网页/视频广告详情页面

视频广告播放完毕

- (void)splashVideoAdDidPlayFinish:(BUSplashAd *)splashAd didFailWithError:(NSError *)error;


点睛接入-新接口概览[V4700+]

开屏点睛广告:5s-30s的开屏广告,在5s开屏呈现的过程中用户点击右上角的“跳过”或5s曝光结束后将收缩到APP内右下角的小视窗继续展示。

设置点睛、展示点睛

在初始化方法中设置属性、相关代理:

复制

SDK内部会判断本次广告是否会展示点睛,并且在需要展示点睛的时机提供splashZoomOutReadyToShow 回调,开发者只需要在该回调中调用show方法展示即可。

注:传入的viewContrller应为应用的根视图控制器。

复制

自定义点睛动画

SDK支持开发者自定义点睛的缩放动画,并且提供开屏的最后一帧视图splashViewSnapshot作为动画起点:

复制

点睛回调说明

时机

方法

说明

点睛即将展示

- (void)splashZoomOutReadyToShow:(BUSplashAd *)splashAd;

点睛此时可以展示

点睛点击

- (void)splashZoomOutViewDidClick:(BUSplashAd *)splashAd;

点睛广告被点击

点睛关闭

- (void)splashZoomOutViewDidClose:(BUSplashAd *)splashAd;

点睛被关闭

点睛在开屏广告关闭后展示

接入须知[V4700+]

1、自渲染&模板渲染 rit位:新版本不区分渲染方式的rit位

2、开屏内部相关的视图生命周期由SDK管理,开发者关注BUSplashAd对象。当BUSplashAd被非法释放时,开屏内部视图会被同时移除释放。

3、接入开屏的最佳实践,在loadSuccess回调中调用show方法展示广告。

4、开屏视图关闭后,splashView即被释放(nil),如在开屏结束后依赖开屏视图做动画,可以使用splashViewSnapshot对象。

5、rootViewController建议使用应用当前window对象的rootViewController(keyWindow.rootViewController)或者当前视图控制器的根控制器navigationController(viewController.navigationController)。如果使用新创建的viewController,注意在开屏广告视图控制器关闭回调中splashAdViewControllerDidClose:从当前控制器堆栈中移除viewController:

复制

6、loadAdData方法不是线程安全的,请尽量在主线程调用。

开屏接入-旧接口概览[V<4700]

创建广告位对象、请求广告、展示广告

广告位对象创建时必须传入广告位ID:

复制

广告物料、素材加载成功后,会回调splashAdDidLoad:方法,在这里调用展示广告即可:

复制

开屏相关代理回调中关闭当前视图控制器:

复制

超时时长设置

超时的计算逻辑:穿山甲从开发者加载广告开始倒计时(注意并非从SDK初始化开始计时),若广告在倒计时结束之前完成广告加载,则会为开发者响应广告。若倒计时结束前未完成广告加载,则将响应超时。建议开发者:

复制

自定义跳过按钮

SDK支持开发者自定义跳过按钮, 通过设置hideSkipButton属性,控制SDK内跳过按钮隐藏:

复制

实现方法事例:

复制

自定义底部logo设置

开发者可自定义开屏底部View,用于logo展示等个性化设置。

复制


开屏回调说明

时机

方法

说明

广告物料、素材加载成功


- (void)splashAdDidLoad:(BUSplashAdView *)splashAd;


物料加载成功,可以在这个回调中展示开屏

广告物料、素材加载失败

- (void)splashAd:(BUSplashAdView *)splashAd didFailWithError:(NSError * _Nullable)error;


返回的错误码(error)表示广告加载失败的原因,所有错误码详情请见链接Link

广告即将展示

- (void)splashAdWillVisible:(BUSplashAdView *)splashAd;


广告关闭


- (void)splashAdDidClose:(BUSplashAdView *)splashAd;



当用户点击广告时会直接触发此回调,建议在此回调方法中直接进行广告对象的移除操作

广告j即将关闭



- (void)splashAdWillClose:(BUSplashAdView *)splashAd;



广告点击

- (void)splashAdDidClick:(BUSplashAdView *)splashAd;


广告中间页、市场页面关闭

- (void)splashAdDidCloseOtherController:(BUSplashAdView *)splashAd interactionType:(BUInteractionType)interactionType;


此回调在广告跳转到其他控制器时,该控制器被关闭时调用。

interactionType:此参数可区分是打开的appstore/网页/视频广告详情页面

点睛接入-旧接口概览[V<4700]

开屏点睛广告:5s-30s的开屏广告,在5s开屏呈现的过程中用户点击右上角的“跳过”或5s曝光结束后将收缩到APP内右下角的小视窗继续展示。

设置点睛、展示点睛

在初始化方法中设置属性、相关代理:

复制

注:传入的viewContrller应为应用的根视图控制器。

复制

自定义点睛动画

SDK支持开发者自定义点睛的缩放动画:

复制

接入须知[V<4700]

1、自渲染&模板渲染 rit位:新版本不区分渲染方式的rit位。

2、开屏内部相关的视图生命周期由SDK管理,开发者关注BUSplashAd对象。当BUSplashAd被非法释放时,开屏内部视图会被同时移除释放。

3、开屏广告的请求最好放在didFinishLaunchingWithOptions回调方法中进行相关的处理,避免任何形式 相关的处理 。

4、避免出现展示广告的window被提前释放或取错window的情况。

5、在splashAd:didFailWithError:回调方法中做广告对象移除操作,避免广告请求失败时导致的一些特定。

6、确认设置Allow Arbitrary Loads权限,避免某些广告资源无法加载情景的发生。

资源

详细接入可参照demo中的AppDelegate类/BUDSplashViewController类。


本篇目录
联系我们