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. Configuring the SDK
  3. Creating a placement
  4. Creating a banner view
  5. Loading an ad
  6. Listening to ad loading events
  7. Listening to ad audio events
  8. How to adapter the banner size after loading
  9. Disposing of a banner view
  10. Improving parallax ad rendering
  11. Video Header Ad - A specific way to implement your video banner

Overview

Banner ads are loaded and displayed by SASBannerView instances.

To load and display a banner ad, 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 show the banner ad.
  • An object implementing the SASBannerView.BannerListener listener interface to monitor banner ad lifecycle events.

The next sections describe in details how to create and load a banner ad.

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

Configuring the SDK

The Equativ Display 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() of the SASConfiguration shared instance to do so.

This method must be called once, as soon as possible.

Ideally call it in the onCreate() method of your Application class. For instance:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Configure Equativ Display SDK
        SASConfiguration.configure(this)
    }
}

Any ad call performed before calling the configure() method will fail by throwing an IllegalStateException.

Creating a placement

You will need an ad placement to perform an ad call. A placement identifies a part of your inventory where you want to display ads.

Creating an ad placement is done by instantiating a SASAdPlacement object using mandatory parameters site ID, page ID, format ID and an optional keyword targeting String (more info in the API documentation).

val adPlacement = SASAdPlacement(SITE_ID, PAGE_ID, FORMAT_ID, OPTIONAL_KEYWORD_TARGETING)

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.

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. You will find more information on the dedicated section here.

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

Creating a banner view

A banner ad is displayed by an instance of the SASBannerView class.

Since this class is a subclass of the Android View class, there are two ways of instantiating it:

  • In an XML layout file where your banner should be displayed (most straightforward):
      <com.equativ.displaysdk.ad.banner.SASBannerView
      android:id="@+id/banner"
      android:layout_width="match_parent"
      android:layout_height="50dp" />

    You can then assign it to a variable like any other Views you are handling in your app.

  • By code directly:
    val bannerView = SASBannerView(context)

Note that when instantiating a SASBannerView by code, it does not belong to any View hierarchy, it is up to you to add it to your view hierarchy with appropriate Android LayoutParams as you would for any other Android View.

The Layout parameters of a SASBannerView can not use ViewGroup.LayoutParams.WRAP_CONTENT for width or height value as the view would not be able to determine the size of its ad contents while its contents try to dynamically adapt to the size of the view at the same time.

Loading an ad

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

bannerView.loadAd(adPlacement)

The banner creative will be automatically displayed when loaded.

To propose a smooth integration to your users and avoid displaying an empty space in case there is no ad to show, it is advised to hide the SASBannerView instance until an ad is successfully loaded.

To do that, 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 related events) by setting an object implementing the SASBannerView.BannerListener interface on the banner view.

bannerView.bannerListener = object : SASBannerView.BannerListener {
    override fun onBannerAdLoaded(adInfo: SASAdInfo) {
        Log.i("Sample", "Banner loading completed")
    }
    override fun onBannerAdFailedToLoad(exception: SASException) {
        Log.i("Sample", "Banner loading failed: $exception")
    }
    override fun onBannerAdClicked() {
        Log.i("Sample", "Banner was clicked")
    }
}

You can use the onBannerAdLoaded and onBannerAdFailedToLoad methods to show or hide the banner respectively, try to reload an in case of failure, and so on. You will find a list of all the available methods in the API documentation.

The loadAd method of the SASBannerView executes the ad loading task asynchronously in a different thread from the calling thread. Therefore, if the loadAd method is called while a previous ad call is being performed and has not finished yet, it will fail with a SASException of type PENDING_AD_LOADING in the onBannerAdFailedToLoad method of the SASBannerView.BannerListener , if any set.

Listening to ad audio events

You can listen to ad audio events (as well as other banner view events) by implementing the SASBannerView.BannerListener interface on the banner view.

bannerView.bannerListener = object : SASBannerView.BannerListener {
    override fun onBannerAdAudioStart() {
        Log.i(TAG, "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 depending on your apps design.
    }

    override fun onBannerAdAudioStop() {
        Log.i(TAG, "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.
    }
}

All video ads start muted and require user interaction to toggle audio.

How to adapter the 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 aspectRatio parameter of the SASAdInfo instance you received via the onBannerAdLoaded listener method. This aspectRatio property represent the actual width/height ratio of the loaded creative. Then it is up to you to compute the perfect height for your banner based on this ratio.

The best place to add the resizing code is in your onBannerAdLoaded implementation. Here is an example:

override fun onBannerAdLoaded(adInfo: SASAdInfo) {
    // Implementation example
    // Here the computed height is based on the width of the device and the received aspectRatio (if any).
    adInfo.aspectRatio?.let { aspectRatio ->
        val layoutParams = bannerView.layoutParams
        layoutParams.height = (context.resources.displayMetrics.widthPixels / aspectRatio).toInt()
        bannerView.layoutParams = layoutParams
    }
}

Disposing of a banner view

Once you are done using a banner view, typically when its hosting Activity is being destroyed, you must call the onDestroy method of the SASBannerView to release the resources it was using.

/**
* Overriden from Activity class
*/
override fun onDestroy() {
    super.onDestroy();
    bannerView.bannerListener = null
    bannerView.onDestroy()
}

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.

The creative displayed inside the parallax banner view will takes the whole screen by default (minus the navigation bar and the status bar). It means that part of the creative might be hidden by some elements of your UI, especially elements covering the scrollable 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.