Native Ads

Overview

Native ads are loaded using a SASNativeAdManager.

Unlike other ad format, a native ad is composed of assets only loaded by the Smart Display SDK but rendered by your app. 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 necessary to load and render a native ad.

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

Configuring the SDK

The Smart 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 at least once, as soon as possible.
Ideally call it in the onCreate() method of your Application class. For instance:

public class MyApplication extends MultiDexApplication {
  @Override
  public void onCreate() {
    super.onCreate();

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456);
  }

class MyApplication : MultiDexApplication() {
  @Override
  public void onCreate() {
    super.onCreate()

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456)
  }

Any subsequent valid call to the configure() method will update the current configuration with the newly supplied parameters.

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 that and can be null (more info in the API documentation).

  SASAdPlacement adPlacement = new SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING);
  

  val adPlacement = SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING)
  

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. This is done by using one of the constants of the SASAdPlacement class.

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, and assign a SASNativeAdManagerListener listener to the SASNativeAdManager to handle ad call outcome (success or failure). Eventually call the loadNativeAd() method to trigger the ad call

// Create a native ad manager, initialized with the placement.
mNativeAdManager = new SASNativeAdManager(context, adPlacement);

// Create the native ad manager listener.
mNativeAdManager.setNativeAdListener(new SASNativeAdManager.NativeAdListener() {
  @Override
  public void onNativeAdLoaded(SASNativeAdElement nativeAdElement) {
    // the native ad is loaded, proceed to rendering..
  }

  @Override
  public void onNativeAdFailedToLoad(Exception e) {
    // the native ad loading failed
  }
});

// Load a native ad
mNativeAdManager.loadNativeAd();

// Create a native ad manager, initialized with the placement.
nativeAdManager = SASNativeAdManager(this, adPlacement)

// Create the native ad manager listener.
nativeAdManager.nativeAdListener = object : SASNativeAdManager.NativeAdListener {
  override fun onNativeAdLoaded(nativeAdElement: SASNativeAdElement?) {
    // the native ad is loaded, proceed to rendering..
  }

  override fun onNativeAdFailedToLoad(e: Exception?) {
    // the native ad loading failed
  }
}

// Load a native ad
nativeAdManager.loadNativeAd()

Handler mainLooperHandler = new Handler(Looper.getMainLooper());
mainLooperHandler.post(new Runnable() {
  @Override
  public void run() {
    // execute you UI sensitive code here
  }
});

  Handler(Looper.getMainLooper()).post {
  // execute you UI sensitive code here
}

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

Rendering the native ad

To render the native ad, simply take the available assets of the SASNativeAdElement 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 on the ad. Check the API documentation for a complete list of all properties.

Using the ad choices view

The Smart Display SDK provides an ad choices icon view that will redirect to a web page providing information to users about the ads they see.
If you wish to add such icon to your natives ads, which is a recommended integration, simply add the SASAdChoicesView component to your native ad rendering UI, and connect it with the native ad being rendered using the setNativeAdElement() method.

        <com.smartadserver.android.library.ui.SASAdChoicesView
                    android:id="@+id/adChoicesView"
                    android:background="#FFFFFF"
                    android:layout_weight="0"
                    android:padding="3dp"
                    android:layout_margin="2dp"
                    android:layout_width="20dp"
                    android:layout_height="20dp" />
          
        

// get ad choices view instance defined in XML
SASAdChoicesView adChoicesView = (SASAdChoicesView) itemView.findViewById(R.id.adChoicesView);

// associate ad choices view with current native ad received above
adChoicesView.setNativeAdElement(nativeAdElement);

// associate ad choices view with current native ad received above
adChoicesView.setNativeAdElement(nativeAdElement)

Using a media view

Some native ads contains a media. You can check the presence of a media using the getMediaElement() method of the SASNativeAdElement instance.

Unlike all others native ad properties, media elements 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 SASNativeAdMediaView that you place in your application UI (best option is to define it in a XML layout file as a View component) and then associate it with the native ad using its setNativeAdElement() method.

        <com.smartadserver.android.library.ui.SASNativeAdMediaView
            android:id="@+id/mediaView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_centerInParent="true">
          
        

// get media view instance defined in XML
SASNativeAdMediaView mediaView = (SASNativeAdMediaView) itemView.findViewById(R.id.mediaView);

// associate media view with current native ad received above
mediaView.setNativeAdElement(nativeAdElement);

// associate media view with current native ad received above
mediaView.setNativeAdElement(nativeAdElement)

Registering views used to render the ad

As soon as a native ad is rendered in the application, the immediate parent View that contains it must be registered with the SASNativeAdElement instance. This step is mandatory as it will ensure impression counting, clicks handling, and viewability tracking on the ad.

To register a view you use to render a native ad, simply call the registerView(View v) method on the SASNativeAdElement instance. You must provide the container View that contains the native ad UI elements.

nativeAdElement.registerView(containerView);

nativeAdElement.registerView(containerView)

Unregistering views

When not used anymore, you must unregister the container view from the native ad by calling the unregisterView (View v) method:

nativeAdElement.unregisterView(containerView);

nativeAdElement.unregisterView(containerView)

Disposing of a native ad manager

Once you are done using a native manager, typically when its hosting Activity is being destroyed, you should call the onDestroy() method of the SASNativeAdManager to release the resources it was using.

/**
 * Overriden from Activity class
 */
@Override
protected void onDestroy() {
  mNativeAdManager.onDestroy();
  super.onDestroy();
}

/**
* Overriden from Activity class
*/
override fun onDestroy() {
  nativeAdManager.onDestroy()
  super.onDestroy()
}