Banner
This page explains how to use the Equativ Display SDK to display a banner ad in your application.
Table of contents
- Overview
- Configuring the SDK
- Creating a placement
- Creating a banner view
- Loading an ad
- Listening to ad loading events
- Listening to ad audio events
- How to adapter the banner size after loading
- Disposing of a banner view
- Improving parallax ad rendering
- Native ad in banner
- 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 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
.
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 can have several values:
- a positive
Double
: The actual aspectRatio of the loaded creative. -
-1
: The best fit for your ad is to use theLayoutParams.WRAP_CONTENT
facilities of Android. -
null
: The SDK does not have any information about the aspectRatio of the ad. We advise you to set a default hardcoded height to your ad.
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 = if (aspectRatio < 0) {
LayoutParams.WRAP_CONTENT
} else {
(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)
Native ad in banner
Starting with Equativ Display SDK v8.3.0 it is possible to display native ad through SASBannerView
. You have nothing more to do than calling with a native ad SASAdPlacement
. You can use the native ad test placements to try it by yourself.
If you want to integrate native ad by using the more advanced integration, please check the native ad integration article.
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.