Native Ads

Overview

Native ads are represented by the SASNativeAd class and are loaded using a SASNativeAdManager.

Unlike other ad format, a native ad is composed of assets that are only loaded by the Smart Display SDK. Your application is responsible of the rendering of these assets. The SDK will still handle anything related to ad loading, impression counting, click handling, …

To load and display a native ad, you will need:

• An fully configured Smart Display SDK.
• An instance of SASAdPlacement, that will be used to perform ad calls to the delivery engine.
• An instance of SASNativeAdManager, that will load the native ad.

The next sections describe the whole process to load and render a native ad.

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

#import <SASDisplayKit/SASDisplayKit.h>

Configuring the SDK

The 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(siteId:) 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 with your own site ID and base URL.
  SASConfiguration.shared.configure(siteId: YOUR_SITE_ID)

  // ...
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // ...

  // Configuring the SDK with your own site ID and base URL.
  [[SASConfiguration sharedInstance] configureWithSiteId:YOUR_SITE_ID];

  // ...
}

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, keywordTargeting: SOME_KEYWORD_TARGETING)

SASAdPlacement *adPlacement = [SASAdPlacement adPlacementWithSiteId:SOME_SITE_ID pageId:SOME_PAGE_ID formatId:SOME_FORMAT_ID keywordTargeting:SOME_KEYWORD_TARGETING];

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

Loading a native ad using a manager

Native ads are loaded using a native ad manager.

To load a native ad, start by creating a new SASNativeAdManager instance using the ad placement defined earlier:

let nativeAdManager = SASNativeAdManager(placement: adPlacement)

SASNativeAdManager *nativeAdManager = [[SASNativeAdManager alloc] initWithPlacement:adPlacement];

nativeAdManager.requestAd({ (ad: SASNativeAd?, error: Error?) in
  if let ad = ad {
    // A valid native ad has been retrieved, it can be rendered…
  } else {
    if let error = error {
      NSLog("Unable to load ad: \(error.localizedDescription)")
    }
  }
})

[nativeAdManager requestAd:^(SASNativeAd * _Nullable ad, NSError * _Nullable error) {
  if (ad) {
    // A valid native ad has been retrieved, it can be rendered…
  } else {
    NSLog(@"Unable to load ad: %@", [error description]);
  }
}];

If you have successfully retrieved the requested ad, you can proceed to the next sections to learn more about how to render and register it.

Rendering the native ad

To render the native ad, take the available assets of the SASNativeAd instance and assign them at your convenience to your native UI elements.

A native ad will always have at least a title, but you should always be flexible on the others properties as they can be available or not depending of the ad. Check the API documentation for a complete list of all properties.

Media

Some native ad contains a media. You can check the presence of a media using the hasMedia property of the SASNativeAd.

Unlike all others native ad properties, media are rendered using a view provided by the Smart Display SDK, called the SASNativeAdMediaView. To use it, you must create a new instance of the media view, position it in your app and then register it with the native ad.

// Retrieve a native ad
// and map the native ad properties to your UI…

// Instantiating a media view
let mediaView = SASNativeAdMediaView(frame: CGRect(x: 0, y: 0, width: 250, height: 200))

// Registering the native ad on the media view
mediaView.registerNativeAd(nativeAd)

// Adding the media view to the hierarchy
view.addSubview(mediaView)

// Retrieve a native ad
// and map the native ad properties to your UI…

// Instantiating a media view
SASNativeAdMediaView *mediaView = [[SASNativeAdMediaView alloc] initWithFrame:CGRectMake(0, 0, 250, 200)];

// Registering the native ad on the media view
[mediaView registerNativeAd:nativeAd];

// Adding the media view to the hierarchy
[self.view addSubview:mediaView];

• you can use one of the SASNativeAd utils methods that will automatically compute the optimal height:
  • for a given width: optimalMediaViewHeight(forWidth:)
  • or a given container view: optimalMediaViewHeight(forContainer:)
• you can compute a size manually depending of the media aspect ratio retrieved using the mediaAspectRatio property,

Registering views used to render the ad

As soon as a native ad has been rendered by the application, the root view (or container view) used to render it must be registered with its SASNativeAd instance. This step is mandatory as it will be used to count the impression, handle clicks, start the viewability tracking on the ad, …

To register views you use to render a native ad, simply call the register(_:modalParentViewController:) method on the SASNativeAd instance. You must provide the root view (or container view) used to render the ad and a reference to the view controller displaying the ad.

nativeAd.register(containerView, modalParentViewController:self)

[self.nativeAd registerView:containerView modalParentViewController:self];

If you don't want the whole container view to be tappable, you can use the register(_:tappableViews: modalParentViewController:) method and provide an array to tappable views.

Unregistering views

When not used anymore (or when reused for another ad), you must unregister the container view from the native ad by calling the unregisterViews() method:

nativeAd.unregisterViews()

[nativeAd unregisterViews];