Interstitial integration for React Native
Integrate interstitial ads in your React Native app by initializing the SDK, creating ad units, and setting up event listeners to manage ad loading and display events.
Read time 4 minutesLast updated 7 months ago
The LevelPlay Interstitial is a full-screen ad unit, usually served at natural transition points during the app lifecycle. We support both static and video interstitials. You can also serve interstitials through the LevelPlay mediation platform.
Note
This documentation is relevant for SDK 8.4.0+.
Prerequisites
- Ensure that you have correctly integrated the React-Native Plugin into your app. Integration is outlined here.
- Ensure that you initialize the SDK using LevelPlay Initialization API.
- Find the AdUnitID in LevelPlay dashboard.
Create Interstitial and Register to Events
The creation of the interstitial object should be done after receiving onInitSuccess callback.
The LevelPlay SDK fires several events to inform you of your Interstitial activity. To receive these events, register the listeners of the ad unit. Make sure you set the listeners before initializing the SDK to prevent any loss of information.
import { LevelPlayInterstitialAd, type LevelPlayInterstitialAdListener, type LevelPlayAdInfo, type LevelPlayAdError} from 'unity-levelplay-mediation'const [interstitialAd, setInterstitialAd] = useState<LevelPlayInterstitialAd>(new LevelPlayInterstitialAd('YOUR_AD_UNIT_ID'))useEffect(() => { interstitialAd.setListener(listener);}, [interstitialAd]);
Set Interstitial Listener
Implement the LevelPlayInterstitialAdListener in your code to get informed of ad delivery.
- It is recommended to set the listener before loading the interstitial ad.
- Each interstitial ad should have its own listener implementation.
- Callbacks run on the main thread.
const listener: LevelPlayInterstitialAdListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is successfully loaded }, onAdLoadFailed: (error: LevelPlayAdError) => { // Provided when the ad fails to load. Ad Unit information is included }, onAdInfoChanged: (adInfo: LevelPlayAdInfo) => { // Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/Rate }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is displayed }, onAdDisplayFailed: (error: LevelPlayAdError, adInfo: LevelPlayAdInfo) => { // Provided when the ad fails to be displayed }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Provided when the user clicks on the ad }, onAdClosed: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is closed }};
Load Interstitial Ad
To load an interstitial ad use loadAd (returns a Promise).
await interstitialAd.loadAd();
Show Interstitial Ad
Show an interstitial ad after you receive the onAdLoaded callback, using showAd.
- If using placements, pass the placement name in the showAd API as shown in the Placements section below.
- After the ad has been successfully displayed to the user, you can load another ad by repeating the loading step.
// Show ad without placementinterstitialAd.showAd();// Show ad with placementinterstitialAd.showAd('YOUR_PLACEMENT');
Check Ad is Ready
To avoid show failures, and to make sure the ad could be displayed correctly, we recommend using the following API, before calling the showAd API.
isAdReady – returns a Promise that resolves to true if the ad was loaded successfully and the ad unit is not capped, or false otherwise.
isPlacementCapped – static method that returns a Promise resolving to true when a valid placement is capped. If the placement is not valid or not capped, it returns false.
// Check that ad is ready and that the placement is not capped (both APIs are async)const isReady = await interstitialAd.isAdReady();const isPlacementCapped = await LevelPlayInterstitialAd.isPlacementCapped('YOUR_PLACEMENT');if (isReady && !isPlacementCapped) { await interstitialAd.showAd('YOUR_PLACEMENT');}
Placements
We support placements pacing and capping for interstitial on the LevelPlay dashboard.
If placements are set up for interstitial ads, call the showAd method to serve the ad for a specific placement.
// Check that ad is ready and that the placement is not capped (both APIs are async)const isReady = await interstitialAd.isAdReady();const isPlacementCapped = await LevelPlayInterstitialAd.isPlacementCapped('YOUR_PLACEMENT');if (isReady && !isPlacementCapped) { await interstitialAd.showAd('YOUR_PLACEMENT');}
Full Implementation Example of Interstitial Ads
import { LevelPlayInterstitialAd, type LevelPlayInterstitialAdListener, type LevelPlayAdInfo, type LevelPlayAdError} from 'unity-levelplay-mediation'// Start of some component ...const [interstitialAd, setInterstitialAd] = useState<LevelPlayInterstitialAd>(new LevelPlayInterstitialAd('YOUR_AD_UNIT_ID'))const listener: LevelPlayInterstitialAdListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Implement your logic here, for example showing the ad interstitialAd.showAd() }, onAdLoadFailed: (error: LevelPlayAdError) => { // Implement your logic here... }, onAdInfoChanged: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdDisplayFailed: (error: LevelPlayAdError, adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdClosed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... } }; useEffect(() => { interstitialAd.setListener(listener) interstitialAd.loadAd() }, []); // Rest of component ...// End of component ...
LevelPlay Mediation Demo App
The Integration Demo application demonstrates how to integrate interstitial Ad Unit APIs in your app.
Verify your integration with our Integration Test Suite.
Next steps
Follow our integration guides to integrate additional Interstitial Ad networks or configure additional ad formats: