Interstitial Ads

Interstitial ads are full-screen ads that cover the interface. Display them at natural pause points in your app, such as between game levels or after completing a task.

Each ad format uses a Zone ID to identify the ad placement. Zone IDs are configured in the Empower dashboard.

Note: All ad status listeners are optional. The SDK handles ad loading and display automatically. Use listeners only if you need to track ad states for analytics, UI updates, or custom logic.

---

Quick Start

import 'dart:async';
import 'dart:io';
import 'package:empower_mobile_ads/empower_mobile_ads.dart';

final zoneId = Platform.isAndroid ? 'ANDROID_ZONE_ID' : 'IOS_ZONE_ID';

// Step 1: Preload the interstitial
EmpowerAds.loadInterstitialAd(zoneId);

// Step 2: Listen for status (optional)
final subscription = EmpowerAds.onInterstitialStatusChanged.listen((event) {
  final status = event['status'];
  if (status == 'ready') {
    print('Interstitial ready to show');
  }
});

// Step 3: Show at a natural break point
void onLevelComplete() {
  EmpowerAds.showInterstitial(zoneId);
}

---

Loading Interstitials

Load interstitial ads in advance so they're ready when needed:

import 'package:empower_mobile_ads/empower_mobile_ads.dart';

// Load with zone ID
await EmpowerAds.loadInterstitialAd('YOUR_ZONE_ID');

The method returns a Future<bool> that resolves to true when the ad starts loading.

---

Showing Interstitials

import 'package:empower_mobile_ads/empower_mobile_ads.dart';

Future<void> showInterstitialIfReady() async {
  final shown = await EmpowerAds.showInterstitial('YOUR_ZONE_ID');
  if (!shown) {
    print('Interstitial not ready yet');
  }
}

---

Listening to Interstitial Status (Optional)

import 'dart:async';
import 'package:empower_mobile_ads/empower_mobile_ads.dart';

final zoneId = 'YOUR_ZONE_ID';

final subscription = EmpowerAds.onInterstitialStatusChanged.listen((event) {
  final status = event['status'];

  switch (status) {
    case 'ready':
      // Ad is ready to be shown
      break;
    case 'failed':
      // Ad failed to load — retry later
      break;
    case 'shown':
      // Ad is being displayed
      break;
    case 'skipped':
      // User dismissed the ad — preload the next one
      EmpowerAds.loadInterstitialAd(zoneId);
      break;
  }
});

// Clean up when no longer needed
subscription.cancel();

---

Complete Example

import 'dart:async';
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:empower_mobile_ads/empower_mobile_ads.dart';

class GameScreen extends StatefulWidget {
  @override
  State<GameScreen> createState() => _GameScreenState();
}

class _GameScreenState extends State<GameScreen> {
  int _level = 1;
  bool _adReady = false;
  StreamSubscription? _interstitialSub;
  StreamSubscription? _sdkReadySub;

  final String _zoneId = Platform.isAndroid ? 'ANDROID_ZONE_ID' : 'IOS_ZONE_ID';

  @override
  void initState() {
    super.initState();

    // Listen for interstitial status changes
    _interstitialSub = EmpowerAds.onInterstitialStatusChanged.listen((event) {
      final status = event['status'];
      if (status == 'ready') {
        setState(() => _adReady = true);
      } else if (status == 'skipped' || status == 'failed') {
        setState(() => _adReady = false);
        // Reload for next time
        EmpowerAds.loadInterstitialAd(_zoneId);
      }
    });

    // Wait for the SDK to be ready, then load the interstitial.
    _sdkReadySub = EmpowerAds.onSdkReady.listen((_) {
      EmpowerAds.loadInterstitialAd(_zoneId);
      _sdkReadySub?.cancel();
    });
  }

  @override
  void dispose() {
    _interstitialSub?.cancel();
    _sdkReadySub?.cancel();
    super.dispose();
  }

  void _completeLevel() {
    setState(() => _level++);

    // Show interstitial every 3 levels
    if (_level % 3 == 0 && _adReady) {
      EmpowerAds.showInterstitial(_zoneId);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Level $_level', style: const TextStyle(fontSize: 24)),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _completeLevel,
              child: const Text('Complete Level'),
            ),
          ],
        ),
      ),
    );
  }
}

---

Best Practices

• Wait for SDK readiness — Load interstitial ads after the SDK signals it is ready via the onSdkReady stream.
• Preload ads — Load ads before you need them for instant display
• Natural break points — Show ads at logical pauses (level complete, article end, screen transitions)
• Don't interrupt — Avoid showing during active gameplay or content consumption
• Reload after use — Load a new ad after each display using the USED status callback
• Frequency capping — The SDK respects server-configured frequency caps

---

Ad Status Reference

Status	Description
INITIALIZING	Ad is loading
READY	Ad is loaded and ready to display
FAILED	Ad failed to load
SHOWN	Ad is being displayed
SKIPPED	User dismissed the ad
USED	Ad was shown and closed
WILL_LEAVE	User clicked the ad (leaving app)