Banner

This page explains how to use the Equativ Display SDK to display a banner ad in your application.

Table of contents

  1. Overview
  2. Importing the SDK
  3. Configuring the SDK
  4. Creating a placement
  5. Banner view instantiation and ad loading
  6. Listening to ad loading events
  7. Listening to ad audio events
  8. Adapting the banner size to the creative size
  9. Improving parallax ad rendering
  10. Video Header Ad - A specific way to implement your video banner

Overview

Banners are displayed using a SASBannerView instance.

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

  • A fully configured Equativ 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

Configuring the SDK

The SDK needs to be configured before making any ad calls. You will have to call the method configure() 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
  SASConfiguration.shared.configure()

  // ...
}

Note that any ad call performed before calling the configure() method will fail.

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)

You can add several information to your ad placements in order to increase the monetization.

For instance you can provide a Seller Defined Audience object, or a Supply Chain Object if your are an inventory reseller.

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).

Don’t forget to remove all test placements before releasing your app!

A banner is displayed using a SASBannerView view instance.

Note that you should always set the current UIViewController as the modalParentViewController of the banner view. The banner might not be able to expand or handle click events properly if you don’t provide this information.

// Instantiating the banner view
let bannerView = SASBannerView(frame: .zero)

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

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

// Add some constraints to position the view in your view hierarchy…

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

bannerView.loadAd(with: adPlacement)

The ad will be automatically displayed when ready.

Note that it is recommended to hide the banner when the ad is loading or if the ad loading fails. 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.

bannerView.delegate = self

There is a lot of optional methods that can be implemented, but the two methods related to ad loading are required:

func bannerView(_ bannerView: SASBannerView, didLoadWith adInfo: SASAdInfo) {
    print("Banner ad loaded with info: \(adInfo)")

    // Display your banner here and resize it using the `ratio` found in the `adInfo` parameter…
}

func bannerView(_ bannerView: SASBannerView, didFailToLoad error: Error) {
    print("Banner did fail to load with error: \(error)")
    
    // Hide your banner here if it was already displayed…
}

You can find all the delegate’s methods in the API documentation.

Listening to ad audio events

You can listen to ad audio events (as well as other banner view events) by implementing the SASBannerViewDelegate protocol.

bannerView.delegate = self

The two optional delegate methods related to ad audio are:

func bannerViewWillStartAudioPlayback(_ bannerView: SASBannerView) {
    print("Banner video ad will start to play audio")

    // Equativ Display SDK is notifying your app that it will play audio. You could optionally
    // pause music and/or manipulate your audio session category depending on your apps design.
}

func bannerViewDidStopAudioPlayback(_ bannerView: SASBannerView) {
    print("Banner video ad did stop to play audio")

    // Equativ Display SDK is notifying your app that it has stopped playing audio. Depending 
    // on your apps design, you could resume music here and/or restore your audio session category.
}
  • The SDK does not modify the app’s audio session category, so the app should handle it within the delegate methods.
  • All video ads start muted and require user interaction to toggle audio.
  • Developers should ensure that any changes to the audio session category are reverted in the dealloc of the ViewController, because the bannerViewDidStopAudioPlayback delegate method will not be called if the banner view is deallocated before the end of the ad.

Adapting the banner size to the creative size

Although the SASBannerView instance takes care of resizing the creative to make it fit properly the banner view size while preserving its ratio, you can go further and resize the banner view 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…

The current creative aspect ratio can be fetched directly from the SASAdInfo object retrieved in the banner(_:didLoadWith:) delegate method.

An easy way to use this ratio is to put an aspect ratio constraint on the SASBannerView . Note that the aspect ratio property can be nil in some rare cases: if it happens use a default value like 320/50.

func bannerView(_ bannerView: SASBannerView, didLoadWith adInfo: SASAdInfo) {
    let ratio = adInfo.aspectRatio?.floatValue ?? 320/50
    NSLayoutConstraint.activate([
        bannerView.widthAnchor.constraint(equalTo: bannerView.heightAnchor, multiplier: CGFloat(ratio))
    ])
}

Check the samples to get more examples on how to integrate a banner view in different layouts (plain view controller, table views, …).

Improving parallax ad rendering

The banner view can be used to display parallax ads. A parallax ad is an inline ad which shows part of a full screen ad under the app content during scroll interactions. It supports images, agency scripts and HTML 5 creatives.

The SASBannerView can automatically display this type of ads when integrated into any scrollable view that inherits from UIScrollView.

The creative displayed inside the parallax banner view will takes the whole screen by default (minus the app window safe areas). It means that part of the creative might be hidden by some UI elements of your app, such as:

  • the navigation bar
  • the tab bar
  • any other custom UI elements that might cover the scroll view

You can prevent part of the ad to be hidden by the UI by defining custom parallax margins on your SASBannerView instance by providing a SASParallaxMargins instance to the parallaxMargins property:

bannerView.parallaxMargins = SASParallaxMargins(left: 10, top: 50, right: 10, bottom: 20)

Video Header Ad - A specific way to implement your video banner

The banner view can be used as a video header ad format, following a specific integration in your application. To help you doing so, we have created integration samples and external classes to add to your app to integrate this new video header ad format as easily as possible. You’ll find more information in the dedicated article.

Back to top

Copyright Equativ © 2024. All right reserved.

Page last modified: Oct 23 2024.