# Android > Integration guides > Native Ad

Source: https://help-display-sdk.equativ.com/android/integration/native-ad.html

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

---

## Overview

Native ads are loaded and displayed by [`SASNativeAdView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) instances.

To load and display a native ad, you will need:
- A fully configured **Equativ Display SDK**.
- An instance of [`SASAdPlacement`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html) that will be used to perform ad calls to the delivery engine.
- An instance of [`SASNativeAdView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) that will load and show the native ad.
- An object implementing the [`SASNativeAdView.NativeAdListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/index.html) 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](https://github.com/smartadserver/equativ-display-sdk-samples-android) 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()`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/configure.html) of the [`SASConfiguration`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/index.html) 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:

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Configure Equativ Display SDK
        SASConfiguration.configure(this)
    }
}
```

Any ad call performed before calling the [`configure()`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/configure.html) 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html) object using mandatory parameters _site ID_, _page ID_, _format ID_ and an optional _keyword targeting_ String (more info [in the API documentation](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html)).

```kotlin
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_](https://help-display-sdk.equativ.com/sellerdefinedaudience.html.md) object, or a [_Supply Chain Object_](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/supply-chain-object-string.html) 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](https://help-display-sdk.equativ.com/android/troubleshooting.html#test).

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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) 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):
    ```xml
    <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:
    ```kotlin
val nativeAdView = SASNativeAdView(context)
    ```

Note that when instantiating a [`SASNativeAdView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) 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.

```kotlin
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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/index.html) interface on the native ad view.

```kotlin
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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/on-native-ad-loaded.html) and [`onNativeAdFailedToLoad`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/on-native-ad-failed-to-load.html) 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](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/index.html).

The [`loadAd`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/load-ad.html) method of the [`SASNativeAdView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) executes the ad loading task asynchronously in a different thread
from the calling thread. Therefore, if the [`loadAd`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/load-ad.html) method is called while a previous ad call is being performed and has not finished yet,
it will fail with a [`SASException`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.exception/-s-a-s-exception/index.html) of type `PENDING_AD_LOADING` in the [`onNativeAdFailedToLoad`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/on-native-ad-failed-to-load.html) method of the [`SASNativeAdView.NativeAdListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/index.html), 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/on-destroy.html) method of the [`SASNativeAdView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/index.html) to release the resources it was using.

```kotlin
/**
* 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/on-native-ad-view-binder-requested.html) method of the [`SASNativeAdView.NativeAdListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/index.html) to provide your custom layout to the **Equativ Display SDK**.

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

You have to create a [`SASNativeAdViewBinder`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view-binder/index.html) 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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view-binder/index.html)'s `Builder` class. Then you will have set every UI element ID on the view binder:
```kotlin
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](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view-binder/-builder/index.html).

You can also provide an already inflated view instead of the LayoutId:
```kotlin
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`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-native-ad-assets/index.html) instance given as parameter of [`onNativeAdViewBinderRequested`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.nativead/-s-a-s-native-ad-view/-native-ad-listener/on-native-ad-view-binder-requested.html).
> You can find several examples of integration in the [samples](https://github.com/smartadserver/equativ-display-sdk-samples-android).

## Displaying native ad through SASBannerView

Starting with **Equativ Display SDK** __v8.3__ you can also display native ads within a [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) in a very seamless way. To do so,
simply follow the [SASBannerView integration article](https://help-display-sdk.equativ.com/android/integration/banner.html.md),
and load any native ad placement. The received native ad will be rendered in a default layout and displayed inside the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html).