Native Ad

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

Table of contents
Overview
Configuring the SDK
Creating a placement
Creating a native ad view
Loading an ad
Listening to ad loading events
Disposing of a native ad view
Native ad rendering
1. Default implementation
2. Advanced implementation
Displaying native ad through SASBannerView

Overview

Native ads are loaded and displayed by SASNativeAdView instances.

To load and display a native 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 SASNativeAdView that will load and show the native ad.
An object implementing the SASNativeAdView.NativeAdListener listener interface to monitor native ad lifecycle events.

The next sections describe in details how to create and load a native 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 native ad view

A native ad is displayed by an instance of SASNativeAdView 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.nativead.SASNativeAdView
      android:id="@+id/native_ad"
      android:layout_width="match_parent"
      android:layout_height="wrap_content" />

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

By code directly:

val nativeAdView = SASNativeAdView(context)

Note that when instantiating a SASNativeAdView 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 SASNativeAdView used should be ViewGroup.LayoutParams.WRAP_CONTENT for width or height. As the view is fully native it is the best solution to have a rightfully sized native ad.

Loading an ad

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

nativeAdView.loadAd(adPlacement)

The native ad 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 SASNativeAdView 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 native ad view related events) by setting an object implementing the SASNativeAdView.NativeAdListener interface on the native ad view.

nativeAdView.nativeListener = object : SASNativeAdView.NativeListener {
    override fun onNativeAdLoaded(adInfo: SASAdInfo, nativeAdAssets: SASNativeAdAssets) {
        Log.i("Sample", "Native ad loading completed")
    }
    override fun onNativeAdFailedToLoad(exception: SASException) {
        Log.i("Sample", "Native ad loading failed: $exception")
    }
    override fun onNativeAdClicked() {
        Log.i("Sample", "Native ad was clicked")
    }
    override fun onNativeAdRequestClose() {
        Log.i("Sample", "Native ad request close")
    }
}

You can use the onNativeAdLoaded and onNativeAdFailedToLoad methods to show or hide the native ad view 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 SASNativeAdView 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 onNativeAdFailedToLoad method of the SASNativeAdView.NativeAdListener , if any set.

Disposing of a native ad view

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

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

Native ad rendering

Default implementation

Starting with the Equativ Display SDK v8.3 the native ad is fully rendered internally. No need for the publisher to handle the rendering on his side from the native ad assets.

The Equativ Display SDK will automatically choose between several default layouts to always use the most suitable one for the received native ad.

Advanced implementation

However, you are also able to display the native ad in your own custom layout. For this you will have to implement the optional onNativeAdViewBinderRequested method of the SASNativeAdView.NativeAdListener to provide your custom layout to the Equativ Display SDK.

 override fun onNativeAdViewBinderRequested(nativeAdAssets: SASNativeAdAssets): SASNativeAdViewBinder? {
    // …
 }

You have to create a SASNativeAdViewBinder instance to let the Equativ Display SDK know which layout to use and how to use it to render the native ad in it.

You can do it with the SASNativeAdViewBinder ‘s Builder class. Then you will have set every UI element ID on the view binder:

val viewBinder = SASNativeAdViewBinder.Builder(R.layout.custom_native_ad)
    .setTitleTextViewId(R.id.title_textview)
    .setBodyTextViewId(R.id.body_textview)
    .setIconContainerViewGroupId(R.id.icon_image_container)
    // … 
    .build()

Every given ID will be used to retrieve the corresponding UI element, and might lead to an error and prevent the ad to be rendered. The IDs you provide must exist in your layout and must point to UI elements of the expected type. You will find more information in the API documentation.

You can also provide an already inflated view instead of the LayoutId:

val layoutViewGroup = layoutInflater.inflate(R.layout.custom_native_ad, binding.root, false) as ViewGroup
val viewBinder = SASNativeAdViewBinder.Builder(layoutViewGroup)
    // …
    .build()

Please note that the Equativ Display SDK will never update your custom layout itself. Therefore, you are responsible for hiding the relevant view if necessary, typically when some assets are empty.

To do so, you can use the SASNativeAdAssets instance given as parameter of onNativeAdViewBinderRequested . You can find several examples of integration in the samples.

Starting with Equativ Display SDK v8.3 you can also display native ads within a SASBannerView in a very seamless way. To do so, simply follow the SASBannerView integration article, and load any native ad placement. The received native ad will be rendered in a default layout and displayed inside the SASBannerView .