Flutter

The Ezoic Flutter SDK lets you use Ezoic mobile app ads (banner, native, outstream video, instream video, rewarded, and interstitial) from Flutter while relying on the native Android and iOS SDKs for ad loading, Prebid, Google Ad Manager, consent handling, pageview tracking, and remote configuration.

The Flutter package is a plugin bridge over the native SDKs. It does not reimplement the ad stack in Dart.

Requirements

• Flutter 3.19 or higher
• Dart 3.3 or higher
• Android SDK 24 or higher for Android apps
• iOS 14.0 or higher for iOS apps
• Google Mobile Ads application ID provided by Ezoic
• Native Android and iOS Ezoic SDK access for the platforms you support

Installation

Add the Flutter package version provided by Ezoic:

dependencies:
  ezoic_flutter_sdk:
    git:
      url: https://github.com/ezoic/flutter-sdk.git

Then install iOS pods if your app supports iOS:

cd ios
pod install

The Flutter plugin expects the native iOS SDK to be available to CocoaPods as EzoicAdsSDK. If Ezoic provides the iOS SDK through a private spec repo or direct pod declaration, add that source to your app's Podfile before running pod install.

Platform Setup

Flutter apps still need the native platform setup required by Android and iOS.

Android

Follow the Android setup requirements in the Android guide, including:

• Making sure Gradle can resolve the Ezoic Android SDK dependency
• Adding the Google Mobile Ads application ID to AndroidManifest.xml
• Adding the advertising ID permission if your app targets Android 12 or higher and uses the advertising ID

The Google Mobile Ads application ID is usually provided by Ezoic and can be found in your Ezoic dashboard.

iOS

Follow the Required App Setup for Ads to Serve in the iOS guide. These steps live in your app's Info.plist (and on your website) and directly affect fill, so complete all of them:

• Installing the Ezoic iOS SDK version provided for your app
• Adding the Google Mobile Ads application ID (GADApplicationIdentifier) and GADIsAdManagerApp to Info.plist
• Adding NSUserTrackingUsageDescription to Info.plist (the SDK presents the App Tracking Transparency prompt for you before loading ads — biggest impact on fill)
• Adding the SKAdNetworkItems identifiers to the app's Info.plist (Apple does not read these from frameworks/SDKs)

The Google Mobile Ads application ID is usually provided by Ezoic and can be found in your Ezoic dashboard.

app-ads.txt

For both platforms, host an app-ads.txt file at the root of the developer website listed on your app's store page (for example, https://example.com/app-ads.txt). It authorizes the buyers that may sell your inventory; a missing or incomplete file causes most programmatic demand to be filtered out. Ezoic provides the required entries — confirm the file is published and current.

Initialize the SDK

Initialize Ezoic before rendering ads.

import 'package:ezoic_flutter_sdk/ezoic_flutter_sdk.dart';

await EzoicAds.initialize(
    const EzoicConfiguration(
        domain: 'example.com',
        debugEnabled: false,
        testMode: false
    ),
);

domain must match the domain configured for your site in Ezoic. The native Android and iOS SDKs both authenticate using the configured domain plus the app's bundle/package identifier — there is no client-side API key.

Add a Banner Ad

Render EzoicBannerView where the banner should appear.

EzoicBannerView(
    adUnitIdentifier: '12345',
    size: EzoicBannerSize.mediumRectangle,
    onLoad: () => print('Ezoic banner loaded'),
    onError: (error) => print('Ezoic banner failed: ${error.message}'),
)

Replace 12345 with your Ezoic ad unit identifier. The native SDKs fetch the Google Ad Manager ad unit, Prebid configuration, targeting values, supported sizes, and refresh interval from Ezoic servers.

Banner Sizes

Common banner sizes include:

• EzoicBannerSize.banner: 320x50
• EzoicBannerSize.largeBanner: 320x100
• EzoicBannerSize.mediumRectangle: 300x250
• EzoicBannerSize.fullBanner: 468x60
• EzoicBannerSize.leaderboard: 728x90

On Android, the selected size is passed into the native SDK's ad request. On iOS, the native SDK selects the configured ad size from Ezoic remote configuration, and the Flutter size controls the platform view dimensions.

Banner Events

EzoicBannerView supports these event callbacks:

• onLoad
• onError
• onImpression
• onClick
• onOpen
• onClose

Add a Rewarded Ad

Rewarded ads are full-screen ads that grant an in-app reward when the user finishes watching. Unlike banners, they are not widgets: load one imperatively ahead of time (for example, at the start of a level), then present it at a natural break. show() resolves with the earned reward, or null if the user dismissed the ad early.

import 'package:ezoic_flutter_sdk/ezoic_flutter_sdk.dart';

Future<void> runRewardedAd() async {
    try {
        final ad = await EzoicRewardedAd.load('12345');

        // Optional: observe lifecycle events
        ad.onDismissed = () => print('Rewarded ad closed');
        ad.onFailedToShow = (error) => print('Show failed: ${error.message}');

        final reward = await ad.show();
        if (reward != null) {
            print('Earned ${reward.amount} ${reward.type}');
            grantReward(reward.amount);
        }
    } catch (error) {
        print('Rewarded ad failed: $error');
    }
}

Replace 12345 with your Ezoic ad unit identifier (passed as a string). Load and show are separate steps; calling show() before the ad has loaded throws. Rewarded ads are single-use — load a new EzoicRewardedAd for each reward opportunity.

The reward type and amount come from the reward configured on the Google Ad Manager rewarded ad unit. The other lifecycle callbacks are onShown, onImpression, onClicked, and onUserEarnedReward — all optional.

Add an Interstitial Ad

Interstitial ads are full-screen ads shown at natural transition points (for example, between levels or screens). Unlike rewarded ads, they grant no reward. Like rewarded ads, they are not widgets: load one imperatively ahead of time, then present it at a natural break. show() resolves when the ad is dismissed, or throws an EzoicInterstitialAdError if it fails to present.

import 'package:ezoic_flutter_sdk/ezoic_flutter_sdk.dart';

Future<void> runInterstitialAd() async {
    try {
        final ad = await EzoicInterstitialAd.load('12345');

        // Optional: observe lifecycle events
        ad.onShown = () => print('Interstitial ad shown');
        ad.onFailedToShow = (error) => print('Show failed: ${error.message}');

        await ad.show();
        print('Interstitial ad closed');
    } catch (error) {
        print('Interstitial ad failed: $error');
    }
}

Replace 12345 with your Ezoic ad unit identifier (passed as a string). Load and show are separate steps; calling show() before the ad has loaded throws. Interstitial ads are single-use and auto-destroy once dismissed — load a new EzoicInterstitialAd for each opportunity.

The other lifecycle callbacks are onImpression, onClicked, and onDismissed — all optional.

Add an Outstream Video Ad

Render EzoicOutstreamAdView where the video should appear. Like EzoicNativeAdView, it is a platform view that fills its parent's constraints, so wrap it in a SizedBox (or another constrained parent) to size it.

SizedBox(
    height: 200,
    child: EzoicOutstreamAdView(
        adUnitIdentifier: '12345',
        onLoad: () => print('Ezoic outstream ad loaded'),
        onError: (error) => print('Ezoic outstream ad failed: ${error.message}'),
        onImpression: () => print('Ezoic outstream ad impression'),
        onClick: () => print('Ezoic outstream ad clicked'),
        onOpen: () => print('Ezoic outstream ad opened an overlay'),
        onClose: () => print('Ezoic outstream ad overlay closed'),
    ),
)

Replace 12345 with your Ezoic ad unit identifier (passed as a string). The native SDKs load the ad and render it inline through Google Ad Manager at the size configured on the server.

EzoicOutstreamAdView fills its parent's constraints and destroys its underlying ad with the platform view's lifecycle — no manual destroy() call is required.

EzoicOutstreamAdView supports these event callbacks:

• onLoad
• onError — receives an EzoicOutstreamAdError with message and code
• onImpression
• onClick
• onOpen
• onClose

Add an Instream Video Ad

EzoicInstreamAd is a view-less controller for instream video. Instream video runs inside your app's OWN video content: your app owns the video player and the Google IMA SDK. The controller renders nothing — its deliverable is a Google Ad Manager VAST ad-tag URL you feed to your IMA AdsRequest. Unlike EzoicInterstitialAd, it is multi-use — it is not auto-destroyed, so keep the instance and call load again for the next video.

import 'package:ezoic_flutter_sdk/ezoic_flutter_sdk.dart';

final instream = EzoicInstreamAd('12345');

Future<void> runInstreamAd() async {
    try {
        final tagUrl = await instream.load(contentUrl: playingVideoUrl);
        // Feed tagUrl to your IMA AdsRequest.adTagUrl and request the preroll.
    } catch (error) {
        print('Instream ad failed: $error');
    }
}

// When IMA reports an ad error, walk the floor waterfall to the next tag.
// A null result means the waterfall is exhausted — give up on the preroll.
final next = await instream.getNextAdTagUrl();

// When IMA reports the ad STARTED, fire the Ezoic impression pixel.
await instream.reportImpression();

// Release the controller when the ad unit is no longer needed.
await instream.destroy();

Replace 12345 with your Ezoic ad unit identifier (passed as a string). load({String? contentUrl}) resolves with the tag URL or throws an EzoicInstreamAdError; pass the URL of the video you're playing so it can be folded into the tag for contextual targeting. getNextAdTagUrl() resolves to null once the waterfall is exhausted. reportImpression({double? revenueUsd}) records the impression on the IMA STARTED event; revenueUsd is optional. Call destroy() only when you're done with the ad unit — the controller keeps its state across loads so you can reuse it for the next video.

Add a Native Ad

Native ads deliver ad assets (headline, icon, advertiser, media, body text, and call to action) rendered in a template designed to match the look and feel of your app content, rather than in a fixed banner or full-screen format. Unlike interstitial and rewarded ads, native ads are widgets: render EzoicNativeAdView where the ad should appear in your layout.

SizedBox(
    height: 320,
    child: EzoicNativeAdView(
        adUnitIdentifier: '12345',
        onLoad: () => print('Ezoic native ad loaded'),
        onError: (error) => print('Ezoic native ad failed: ${error.message}'),
        onImpression: () => print('Ezoic native ad impression'),
        onClick: () => print('Ezoic native ad clicked'),
        onOpen: () => print('Ezoic native ad opened an overlay'),
        onClose: () => print('Ezoic native ad overlay closed'),
    ),
)

Replace 12345 with your Ezoic ad unit identifier (passed as a string). The native SDKs load the ad and render it in an SDK-built template through a platform view.

EzoicNativeAdView is a platform view and fills its parent's constraints, so wrap it in a SizedBox (or another constrained parent) to set its size.

The plugin destroys the underlying native ad with the platform view's lifecycle — no manual destroy() call is required.

EzoicNativeAdView supports these event callbacks:

• onLoad
• onError — receives an EzoicNativeAdError with message and code
• onImpression
• onClick
• onOpen
• onClose

Privacy and Consent

The native SDKs can automatically read platform consent signals when they are set by a consent management platform. You can also set consent manually from Flutter:

await EzoicAds.setGDPRConsent(true, 'TCF_CONSENT_STRING');
await EzoicAds.setGPPConsent('GPP_STRING', '7');
await EzoicAds.setSubjectToCOPPA(false);

For platform-specific consent behavior, see the Android privacy section and iOS privacy section.

Pageview Tracking

The native SDKs handle their platform-specific automatic pageview tracking. If your Flutter app uses Dart navigation, you can also track a pageview manually when the active route changes:

await EzoicAds.trackPageview();

Troubleshooting

SDK Not Initializing

1. Confirm the configured domain matches your Ezoic dashboard.
2. Confirm the native Android/iOS Ezoic SDK dependencies are installed for the platform you are building.
3. Enable debugEnabled: true and review platform logs.

Ads Not Loading

1. Initialize Ezoic before rendering EzoicBannerView or EzoicNativeAdView.
2. Confirm the Ezoic ad unit identifier is configured in Ezoic.
3. Confirm the Google Mobile Ads application ID is present in AndroidManifest.xml or Info.plist.
4. Check the platform-specific setup in the Android guide or iOS guide.