> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentignite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interstitial Ads

> Setting up Interstitial ads

Interstitial ads are full-screen ads that cover the interface of the app. They're typically displayed at natural transition points in the flow of the app.

## Initialising an ad

Start by creating an instance of `CIInterstitialAd` with the following parameters. Create one instance per ad you intend to show.

### Required

* `placementId: string`: Unique ID for this Ad Placement provided by Content Ignite.

### Optional

* `pageUrl: string`: URL used for targeting, for example if the ad is displayed in a section of the app which has an equivalent URL on the web.
* `targeting: Record<string, string[]>`: Pass custom key-value pairs to ad requests.
* `eventListener: CIInterstitialEventListener`: Respond to load and dismiss events. See [Handling ad events](#handling-ad-events).

```tsx theme={null}
import { CIInterstitialAd } from '@content-ignite/mobile-sdk-react-native';

const ad = new CIInterstitialAd({
  placementId: '<PLACEMENT-ID>',
  pageUrl: 'https://example.com/sport',
  targeting: { segment: ['health', 'fitness'] },
});
```

## Load the ad

When you are ready to load the ad, call `load()`. It resolves to `true` when an ad is ready and `false` if loading failed:

```tsx theme={null}
const loaded = await ad.load();
if (!loaded) {
  console.warn('Interstitial failed to load');
}
```

## Show the ad

When you are ready to display the ad, such as after a transition in the app flow, call `show()`. Like `load()`, it resolves to a boolean: `true` once the ad has been shown and dismissed, or `false` immediately if no ad was loaded:

```tsx theme={null}
const shown = await ad.show(); // resolves to true once the ad is dismissed
if (!shown) {
  console.warn('No interstitial was ready to show');
}
```

<Note>
  To show another ad after one is dismissed, call `load()` again to prepare a fresh ad.
</Note>

## Handling ad events

To listen and respond to events from an Interstitial ad, pass a `CIInterstitialEventListener` when creating the ad. All callbacks are optional, so provide only the ones you need:

```tsx theme={null}
const ad = new CIInterstitialAd({
  placementId: '<PLACEMENT-ID>',
  pageUrl: 'https://example.com/sport',
  eventListener: {
    interstitialLoaded: () => console.log('Interstitial ad loaded.'),
    interstitialLoadFailed: () => console.warn('Interstitial ad failed to load.'),
    interstitialDismissed: () => console.log('Interstitial ad dismissed.'),
  },
});
```

The listener is complementary to the promises returned by `load()` and `show()` — use whichever style suits your app. The events map to the same signals:

| Callback                 | Also surfaced by          |
| ------------------------ | ------------------------- |
| `interstitialLoaded`     | `load()` resolves `true`  |
| `interstitialLoadFailed` | `load()` resolves `false` |
| `interstitialDismissed`  | `show()` resolves `true`  |

## Releasing the ad

Call `destroy()` to release the native ad, stop listening for events, and free resources — for example when the component that owns the ad unmounts:

```tsx theme={null}
import { useEffect, useRef } from 'react';
import { CIInterstitialAd } from '@content-ignite/mobile-sdk-react-native';

function InterstitialScreen() {
  const adRef = useRef<CIInterstitialAd | null>(null);

  useEffect(() => {
    return () => {
      adRef.current?.destroy();
    };
  }, []);

  const showAd = async () => {
    const ad = new CIInterstitialAd({
      placementId: '<PLACEMENT-ID>',
      pageUrl: 'https://example.com/sport',
      targeting: { segment: ['health', 'fitness'] },
    });
    adRef.current = ad;

    if (await ad.load()) {
      await ad.show(); // resolves once the ad is dismissed
    }
  };

  // ...render a button that calls showAd()
}
```

See the full example: [Interstitial sample app](https://gitlab.com/content-ignite/content-ignite-mobile-sdk-react-native/-/tree/main/examples/example).