Banner

Overview

Banners are displayed using a SASBannerView instance.

To load and display an ad using a banner view, you will need:

• An fully configured Smart Display SDK.
• An instance of SASAdPlacement, that will be used to perform ad calls to the delivery engine.
• An instance of SASBannerView, that will load and display the banner creative.
• A view controller implementing the SASBannerViewDelegate protocol.

The next sections describe the whole process to load and display a banner.

You can also refer to the samples if you just want to copy/paste the complete integration.

Importing the SDK

Before using the SDK, you must import the framework:

import SASDisplayKit

#import <SASDisplayKit/SASDisplayKit.h>

Configuring the SDK

The SDK needs to be configured with your own site ID and base URL before making any ad calls. You will have to call the method configure(siteId:) of SASConfiguration shared instance to do so.

This method should be called as soon as possible. A good place to do it is in your application's delegate, in the application(_:didFinishLaunchingWithOptions:) method.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  // ...

  // Configuring the SDK with your own site ID and base URL.
  SASConfiguration.shared.configure(siteId: YOUR_SITE_ID)

  // ...
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // ...

  // Configuring the SDK with your own site ID and base URL.
  [[SASConfiguration sharedInstance] configureWithSiteId:YOUR_SITE_ID];

  // ...
}

Creating a placement

You will need an ad placement to perform an ad call.

Creating an ad placement is done by instantiating a SASAdPlacement object using a site ID, a page ID and a format ID. You can also provide some additional information, like targeting informations (more information in the API documentation).

let adPlacement = SASAdPlacement(siteId: SOME_SITE_ID, pageId: SOME_PAGE_ID, formatId: SOME_FORMAT_ID, keywordTargeting: SOME_KEYWORD_TARGETING)

SASAdPlacement *adPlacement = [SASAdPlacement adPlacementWithSiteId:SOME_SITE_ID pageId:SOME_PAGE_ID formatId:SOME_FORMAT_ID keywordTargeting:SOME_KEYWORD_TARGETING];

For testing purposes, it is possible to instantiate generic ad placements that will always deliver an ad of a particular format. This is done by using the SASAdPlacement(testAd:) initializer (check the SASAdPlacementTest enum for an exhaustive list of the formats you can get using test placements).

Banner view instantiation and ad loading

A banner is displayed using a SASBannerView that must be instantiated using a frame and an optional loader type.

Note that you should always define an UIViewController attached to the navigation stack as the modalParentViewController of the banner view. If you don't, the banner view will not be able to display post-click modals when the user clicks the ad.

// Instantiating the banner view with a white loader
let banner = SASBannerView(frame: CGRect(x: 0, y: 0, width: view.frame.width, height: 50), loader: .activityIndicatorStyleWhite)

// Setting the modal parent view controller
banner.modalParentViewController = self

// Adding the banner view to the current view controller
view.addSubview(banner)

// Instantiating the banner view with a white loader
SASBannerView *banner = [[SASBannerView alloc] initWithFrame:CGRectMake(0, 0, CGRectGetWidth(self.view.frame), 50) loader:SASLoaderActivityIndicatorStyleWhite];

// Setting the modal parent view controller
banner.modalParentViewController = self;

// Adding the banner view to the current view controller
[self.view addSubview:banner];

When the banner view is properly instantiated, an ad can be loaded using the ad placement created earlier.

banner.load(with: adPlacement)

[banner loadWithPlacement:adPlacement];

The ad will be automatically displayed when ready.

Note that it is recommended to hide the banner if the ad loading failed. You can also add the banner to the view hierarchy only when the ad loading is successful. To do so, you must listen to ad loading events, as described in the next section.

Listening to ad loading events

You can listen to ad loading events (as well as other banner view events) by implementing the SASBannerViewDelegate protocol and becoming the delegate of the banner view.

banner.delegate = self

banner.delegate = self;

There are a lot of optional methods you can implement, but the one you absolutely want are those related to ad loading events.

func bannerViewDidLoad(_ bannerView: SASBannerView) {
	NSLog("Banner has been loaded")
}

func bannerView(_ bannerView: SASBannerView, didFailToLoadWithError error: Error) {
	NSLog("Banner has failed to load with error: \(error.localizedDescription)")
}

- (void)bannerViewDidLoad:(SASBannerView *)bannerView {
  NSLog(@"Banner has been loaded");
}

- (void)bannerView:(SASBannerView *)bannerView didFailToLoadWithError:(NSError *)error {
  NSLog(@"Banner has failed to load with error: %@", [error localizedDescription]);
}

You can use these methods to show or hide the banner, try to reload an ad in case of failure, etc… You will find a list of all the delegate's methods in the API documentation.

How to adapt banner size after loading.

Although the SASBannerView instance takes care of resizing the creative to make it fit properly while preserving its ratio, you can go further and resize the SASBannerView's height to match the creative's width/height ratio, hence eliminating empty spaces around the creative.

This is often the case when your SASBannerView needs to deliver 300x50, 300x250 formats or even 16/9 video, etc…

Use the optimalAdViewHeightForContainer: method of your SASBannerView instance to retrieve the appropriate height for your banner in a given container. This method will compute the perfect height for your banner instance based on creative's width and height ratio.

Please note that you can access the actual creative's width and height (in pixels) through the SASAd object displayed by the SASBannerView.

The best place to add the resizing code is in the bannerView:didDownloadAd: delegate method:

    
func bannerView(_ bannerView: SASBannerView, didDownloadAd ad: SASAd) {
  let optimalHeight = bannerView.optimalAdViewHeight(forContainer: self.view)
  let frame = CGRect(x: bannerView.frame.origin.x, y: bannerView.frame.origin.y, width: bannerView.frame.size.width, height: optimalHeight)
  self.banner?.frame = frame
}

- (void)bannerView:(SASBannerView *)bannerView didDownloadAd:(SASAd *)ad {
  float optimalHeight =  [bannerView optimalAdViewHeightForContainer:self.view];
  CGRect frame = CGRectMake(bannerView.frame.origin.x, bannerView.frame.origin.y, bannerView.frame.size.width, optimalHeight);
  self.banner.frame = frame;
}

How to adapt parallax banner settings for your app

The In-App Parallax is an inline ad which shows a piece of background during scroll interactions. It supports image, agency scripts and html5 (with no interaction).

This format is designed to be displayed inside a SASBannerView attached to Scrollview, this scrollview cannot be zoomable and the parallax effect doesn't apply when scrolling horizontally.

Here are the supported classes (as well as the extended ones):

• UITableView
• UICollectionView
• UIScrollView

By default the parallax animation will use the whole device screen to display the creative, but in some cases, the banner view will not be visible from the bottom to the top of the app, for example in app using:

• Navigation bars
• Tab bars
• Toolbars
• Other custom UI views that could cover the banner view displayed in the scrollview

    
// Compute parallax limits
let topBarSize: CGFloat = YOUR_TOP_BAR_SIZE;
let bottomBarSize: CGFloat = YOUR_BOTTOM_BAR_SIZE;
let parallaxViewportHeight = UIScreen.main.bounds.size.height - topBarSize - bottomBarSize;
// Set parallax infos on your banner view instance
banner.parallaxInfos = SASParallaxInfos(viewportTopOrigin: topBarSize, viewportHeight: parallaxViewportHeight)

// Compute parallax limits
CGFloat topBarSize = YOUR_TOP_BAR_SIZE;
CGFloat bottomBarSize = YOUR_BOTTOM_BAR_SIZE;
CGFloat parallaxViewportHeight = [UIScreen mainScreen].bounds.size.height - topBarSize - bottomBarSize;
// Set parallax infos on your banner view instance
[banner setParallaxInfos:[[SASParallaxInfos alloc] initWithViewportTopOrigin:topBarSize viewportHeight:parallaxViewportHeight]];