Interstitial integration for Flutter
Integrate full-screen interstitial ads in your Flutter app using the Unity LevelPlay SDK, supporting both static and video formats.
Read time 4 minutesLast updated 10 days ago
The LevelPlay Interstitial is a full-screen ad unit, usually served at natural transition points during the app lifecycle. Unity supports both static and video interstitials.
Note
This documentation is relevant for plug-in 9.0.0+.
Prerequisites
- Ensure that you have correctly integrated the LevelPlay Flutter plug-in into your app.
- Ensure that you initialize the SDK using LevelPlay Initialization API.
- Find the AdUnitID in LevelPlay dashboard.
Create Interstitial and Register to Events
Create the interstitial object and set its listener before you load the ad. Load the ad only after you receive the callback.
onInitSuccessThe LevelPlay SDK fires several events to inform you of your Interstitial activity. To receive these events, register the listener of the ad object. Make sure you set the listener before loading the ad to prevent any loss of information.
final LevelPlayInterstitialAd _interstitialAd = LevelPlayInterstitialAd(adUnitId: 'YOUR_AD_UNIT_ID');@overridevoid initState() { super.initState(); _interstitialAd.setListener(this);}
Set Interstitial Listener
Implement the in your code to get informed of ad delivery.
LevelPlayInterstitialAdListener- The recommended best practice is to set the listener before loading the interstitial ad.
- Each interstitial ad must have its own listener implementation.
- Callbacks run on the main thread.
@override void onAdLoaded(LevelPlayAdInfo adInfo) { // Provided when the ad is successfully loaded } @override void onAdLoadFailed(LevelPlayAdError error) { // Provided when the ad fails to load. Ad Unit information is included } @override void onAdDisplayed(LevelPlayAdInfo adInfo) { // Provided when the ad is displayed. This is equivalent to an impression } @override void onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) { // Provided when the ad fails to be displayed } @override void onAdClicked(LevelPlayAdInfo adInfo) { // Provided when the user clicks on the ad } @override void onAdClosed(LevelPlayAdInfo adInfo) { // Provided when the ad is closed } @override void onAdInfoChanged(LevelPlayAdInfo adInfo) { // Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/Rate }
Load Interstitial Ad
To load an interstitial ad use . Call it after you receive the callback.
loadAdonInitSuccess_interstitialAd.loadAd();
Show Interstitial Ad
Show an interstitial ad after you receive the callback, using .
onAdLoadedshowAd- 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 placement _interstitialAd.showAd(); // Show ad with placement _interstitialAd.showAd(placementName: 'YOUR_PLACEMENT');
Check Ad is Ready
To avoid show failures, and to make sure the ad worked correctly, the recommended best practice is to use the following API before calling the API:
showAd-
: Returns true if ad was loaded successfully and ad unit is not capped, or false otherwise.
isAdReady -
: Returns true when a valid placement is capped. If the placement is not valid, or not capped, this API will return false.
isPlacementCapped
Both APIs return a , so call them with inside an function.
Future<bool>awaitasync// Check that ad is ready and that the placement is not cappedFuture<void> showInterstitial() async { if (await _interstitialAd.isAdReady() && !await LevelPlayInterstitialAd.isPlacementCapped('YOUR_PLACEMENT')) { _interstitialAd.showAd(placementName: 'YOUR_PLACEMENT'); }}
Placements
Unity supports placements pacing and capping for interstitial on the LevelPlay dashboard.
If you have set up placements for interstitial ads, call the method to serve the ad for a specific placement.
showAd// Check that ad is ready and that the placement is not cappedFuture<void> showInterstitial() async { if (await _interstitialAd.isAdReady() && !await LevelPlayInterstitialAd.isPlacementCapped('YOUR_PLACEMENT')) { _interstitialAd.showAd(placementName: 'YOUR_PLACEMENT'); }}
Dispose Interstitial Ad
When you no longer need the interstitial ad object (for example, in your widget's ), call to release it. A disposed ad object can no longer be used; create a new to load more ads.
State.disposedisposeLevelPlayInterstitialAd_interstitialAd.dispose();
Full Implementation Example of Interstitial Ads
// Start of the widget...final LevelPlayInterstitialAd _interstitialAd = LevelPlayInterstitialAd(adUnitId: 'YOUR_AD_UNIT_ID'); @override void initState() { super.initState(); _interstitialAd.setListener(this); } // Call after you receive the onInitSuccess callback void loadInterstitial() { _interstitialAd.loadAd(); } @override void dispose() { _interstitialAd.dispose(); super.dispose(); } @override void onAdClicked(LevelPlayAdInfo adInfo) { // Implement your logic here... } @override void onAdClosed(LevelPlayAdInfo adInfo) { // Implement your logic here... } @override void onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) { // Implement your logic here... } @override void onAdDisplayed(LevelPlayAdInfo adInfo) { // Implement your logic here... } @override void onAdInfoChanged(LevelPlayAdInfo adInfo) { // Implement your logic here... } @override void onAdLoadFailed(LevelPlayAdError error) { // Implement your logic here... } @override void onAdLoaded(LevelPlayAdInfo adInfo) { // Implement your logic here, for example showing the ad _interstitialAd.showAd(); } // Rest of the widget // End of widget...
LevelPlay Mediation Demo App
The Integration Demo application demonstrates how to integrate interstitial Ad Unit APIs in your app.
Verify your integration with the Integration Test Suite.
Next steps
Follow the Flutter integration guides to integrate additional Interstitial Ad networks or configure additional ad formats: