---
agentTools:
  projectIndex: https://developers.appnext.com/llms.txt
---

# Interstitial Integration Guide

Appnext Android SDK 2.0 supports Interstitial ads, a full-screen ad unit recommended for natural transition points in your app, such as between levels, after completing an action, or before moving to a new screen.

## Step 1. Create an Interstitial Ad

Create an Interstitial instance using your Appnext placement ID.:

```kotlin
val interstitial = Interstitial("YOUR_PLACEMENT_ID")
```

## Step 2. Load the Interstitial Ad

Before showing an interstitial, call loadAds().

```kotlin
interstitial.loadAds(context)
```

You can also pass an optional load callback:

```kotlin
interstitialAd.loadAds(
    context = context,
    listener = object : InterstitialLoadCallback {
        override fun onInterstitialLoaded() {
            // Ad loaded successfully
        }

        override fun onInterstitialLoadError(error: AppnextError) {
            // Ad failed to load
        }
    }
)
```

Optional search keyword:

```kotlin
interstitialAd.loadAds(
    context = context,
    searchKeyWord = "games"
)
```

## Step 3. Show the Interstitial Ad

After the ad is loaded, call showAd().

```kotlin
interstitialAd.showAd(
    context = context,
    interstitialAdCallbacks = object : InterstitialAdCallbacks {
        override fun onAdShown() {
            // Ad shown
        }

        override fun onAdClosed() {
            // Ad closed
        }

        override fun onAdClicked(packageName: String) {
            // Ad clicked
        }

        override fun onAdError(error: AppnextError) {
            // Ad failed to show
        }
    }
)
```

## Callbacks

**Load Callback**\
Use InterstitialLoadCallback to receive load status.

```kotlin
object : InterstitialLoadCallback {
    override fun onInterstitialLoaded() {}
    override fun onInterstitialLoadError(error: AppnextError) {}
}
```

**Ad Callback**

Use InterstitialAdCallbacks to receive show, close, click, and error events.

```kotlin
object : InterstitialAdCallbacks {
    override fun onAdShown() {}

    override fun onAdClosed() {}

    override fun onAdClicked(packageName: String) {}

    override fun onAdError(error: AppnextError) {}
}
```

## Advanced Settings

Configure the ad before calling loadAds..

```kotlin
interstitial.setPostBack("YOUR_POSTBACK")
interstitial.setCategories("games,tools")
interstitial.setSpecificCategories("arcade,puzzle")
interstitial.setSearchByPackage("com.example.app")
```

Available setters:

* setPostBack - String. Postback parameters that will be posted to your server after the user installs an app.
* setCategories - String. Set preferred ad categories, comma-separated.
* setSpecificCategories - String. Set specific ad categories, comma-separated.
* setSearchByPackage - String. Set a specific Android package.

## (Optional) In-App header bidding

You can get the predicted eCPM value before loading or showing an ad.

```kotlin
interstitialAd.getECPM(
    context = context,
    onECPMLoaded = object : OnECPMLoaded {
        override fun ecpm(ecpm: ECPM) {
            // eCPM received
        }

        override fun error(error: AppnextError) {
            // eCPM request failed
        }
    }
)
```

The ecpm object will include the following getters:

* getEcpm - Returns the predicted ECPM value of the banner that is about to be loaded (float type)
* getPpr - Returns the predicted price per request value (ECPM value / 1000) (float type)
* getCreativeId - String. Returns a unique ID of the campaign's creative.
* getAdDomain- String. Returns the Android package name.
* getCreativeUrl - String. Returns the URL of the campaign for User Acquisition campaign type, or the package name for Re-engagement campaign type.
* getCampaignID - String. Returns a unique ID of the campaign
* getCategory - String. Returns the campaign category name.

Optional search keyword:

```kotlin
interstitialAd.getECPM(
    context = context,
    onECPMLoaded = callback,
    searchKeyword = "games"
)
```