Native Ad

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

Table of contents
Overview
Importing the SDK
Configuring the SDK
Creating a placement
Native ad view instantiation
Loading an ad
Listening to ad loading event
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.
A view controller implementing the SASNativeAdViewDelegate protocol.

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.

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!

Native ad view instantiation

A native ad is displayed using a SASNativeAdView view instance.

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

// Instantiating the native ad view
let nativeAdView = SASNativeAdView(frame: .zero)

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

// Adding the native ad view to the current view controller
view.addSubview(nativeAdView)

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

Loading an ad

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

nativeAdView.loadAd(with: 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 event

You can listen to ad loading events (as well as other native ad view related events) by implementing the SASNativeAdViewDelegate protocol.

func nativeAdView(_ nativeAdView: SASNativeAdView, didLoadWith adInfo: SASAdInfo, nativeAdAssets: SASNativeAdAssets) {
    print("Native ad loaded with info: \(adInfo)")
}

func nativeAdView(_ nativeAdView: SASNativeAdView, didFailToLoad error: Error) {
    print("Native ad did fail to load with error: \(error)")
}

func nativeAdViewClicked(_ nativeAdView: SASNativeAdView) {
    print("Native ad was clicked")
}

func nativeAdViewDidRequestClose(_ nativeAdView: SASNativeAdView) {
    print("Native ad did request close")
}

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

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 nativeAdView(_:didRequestBinderFor:) method of the SASNativeAdViewDelegate protocol to provide your custom layout to the Equativ Display SDK.

 func nativeAdView(_ nativeAdView: SASNativeAdView, didRequestBinderFor 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 SASNativeAdViewBinderBuilder class. Then you will have set every view instances of your layout on the view binder’s builder.

 func nativeAdView(_ nativeAdView: SASNativeAdView, didRequestBinderFor nativeAdAssets: SASNativeAdAssets) -> SASNativeAdViewBinder? {
    // Create your custom view here
    // ...

    // Initialize the builder using your custom view
    let builder = SASNativeAdViewBinderBuilder(baseView: customView)
    // Views binding
    builder.withTitleLabel(customView.titleLabel)
    builder.withBodyLabel(customView.bodyLabel)
    builder.withIconView(customView.iconImageView)
    // ...

    return builder.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 nativeAdView(_:didRequestBinderFor:) . 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 .