Skip to main content

Interstitial Placement

Interstitial is a fullscreen ad shown at a natural break in your app. It is not a widget: the native placement presents itself — in its own Activity on Android, over the key window on iOS — so there is nothing to put in your widget tree.

The lifecycle is preload-then-present: create → load → isReady → show → dispose.

Sample App

The plugin's example app, shipped with the teads_flutter package, includes a working screen for this format. Use it as a reference while you set up this placement.

Example​

class _MyScreenState extends State<MyScreen> {
  InterstitialPlacement? _interstitial;

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

  Future<void> _preload() async {
    final interstitial = await InterstitialPlacement.create(
      config: InterstitialPlacementConfig(
        widgetId: 'INT_MW_1',                // Provided by your Teads account manager
        installationKey: 'YOUR_INSTALLATION_KEY',
        articleUrl: 'https://example.com/article/123',
      ),
    );
    interstitial.onReady = () => debugPrint('Interstitial ready');
    interstitial.onFailed = (error) => debugPrint('Failed: ${error.reason}');
    interstitial.onClosed = () => debugPrint('Dismissed — resume the app');
    await interstitial.load();
    if (!mounted) {
      await interstitial.dispose();
      return;
    }
    setState(() => _interstitial = interstitial);
  }

  Future<void> _showAtNaturalBreak() async {
    final interstitial = _interstitial;
    if (interstitial == null) return;
    // Re-check immediately before showing — see Best Practices.
    if (await interstitial.isReady) {
      await interstitial.show();
    }
  }

  @override
  void dispose() {
    _interstitial?.dispose();
    super.dispose();
  }
}

load() completes when the request has been dispatched, not when the ad is ready — wait for onReady or poll isReady for that. show() returns false when there was nothing to show rather than throwing.

Floor price​

Optional bid floor, in US dollars:

InterstitialPlacementConfig(
  widgetId: 'INT_MW_1',
  installationKey: 'YOUR_INSTALLATION_KEY',
  articleUrl: 'https://example.com/article/123',
  floorPrice: 2.5, // $2.50
)

Both native SDKs type their floor price as a whole integer, so this is rounded to the nearest whole dollar when it crosses the platform channel.

Best Practices​

Check isReady immediately before show(), never cache it

Ads expire on a native TTL (driven by remote config, about an hour by default). When it lapses the placement invalidates itself and isReady becomes false on its own.

Always call dispose()

The native side holds a WebView and an Open Measurement session. Nothing else releases them.

The widget ID selects the format

Pointing an Interstitial at a Feed widget ID (such as MB_1) serves a feed, which looks like a broken placement.

Configuration​

Every InterstitialPlacementConfig field and InterstitialPlacement member is in Settings.

Ad Lifecycle Listener​

Assign onReady, onFailed, onClicked, onClosed and onEvent on the placement before calling load(). See Placement Events Listener.

Checklist​