Skip to main content

Banner Placement

Banner is a fixed-purpose ad slot. Natively, Banner and Feed are the same widget with a different format, so BannerPlacementConfig takes the same fields as FeedPlacementConfig. The widget reserves 100 logical pixels until the real height arrives.

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​

BannerPlacement(
  config: BannerPlacementConfig(
    widgetId: 'MB_10',                   // Provided by your Teads account manager
    installationKey: 'YOUR_INSTALLATION_KEY',
    articleUrl: 'https://example.com/article/123',
  ),
  onReady: () => debugPrint('Banner ready'),
  onFailed: (TeadsAdError error) => debugPrint('Banner failed: ${error.reason}'),
)

Toggling dark mode at runtime​

BannerPlacementConfig.darkMode only sets the value the banner is constructed with. To change it on a loaded banner, hold a BannerController:

class _BannerScreenState extends State<BannerScreen> {
  final _controller = BannerController();
  bool _darkMode = false;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        BannerPlacement(config: bannerConfig, controller: _controller),
        Switch(
          value: _darkMode,
          onChanged: (value) {
            setState(() => _darkMode = value);
            _controller.toggleDarkMode(value);
          },
        ),
      ],
    );
  }
}

Calls made before the banner has loaded are buffered and applied as soon as it does.

iOS: forward rotation events​

Android needs nothing — the plugin observes configuration changes process-wide. UIKit only hands a transition coordinator to a real view controller, so your FlutterViewController must forward it. In ios/Runner/AppDelegate.swift (or your FlutterViewController subclass):

override func viewWillTransition(
    to size: CGSize,
    with coordinator: UIViewControllerTransitionCoordinator
) {
    super.viewWillTransition(to: size, with: coordinator)
    TeadsFlutterPlugin.forwardViewWillTransition(to: size, with: coordinator)
}

Skip this and Banner still works — the ad simply never hears about a rotation.

Best Practices​

One live Banner at a time

The native SDK's test-display flag is a process-wide singleton, and the plugin does not yet guard against multiple concurrent Banner placements — the last one created wins. Keep to one live BannerPlacement at a time.

The widget ID selects the format

Pointing a Banner at a Feed widget ID (such as MB_1) serves a feed, which looks like a broken banner.

Nothing on top of the placement

No widget may cover the placement — not even a transparent overlay. It breaks viewability measurement.

Configuration​

Every BannerPlacementConfig field and BannerPlacement/BannerController member is in Settings.

Ad Lifecycle Listener​

Banner shares the Media/Interstitial callbacks: onReady, onFailed, onClicked, onClickedOrganic and onEvent. See Placement Events Listener.

Checklist​