Flutter

The Ezoic Flutter SDK lets you use Ezoic mobile app ads 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 iOS setup requirements in the iOS guide, including:

  • Installing the Ezoic iOS SDK version provided for your app
  • Adding the Google Mobile Ads application ID to Info.plist
  • Adding NSUserTrackingUsageDescription if your app uses App Tracking Transparency
  • Adding any required SKAdNetwork identifiers

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

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',
        apiKey: 'your-api-key',
        siteId: 'your-site-id',
        debugEnabled: false,
        testMode: false
    ),
);

domain is used by the Android SDK. apiKey and siteId are used by the iOS SDK. Use the values provided for your app in Ezoic.

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.

On Android, the current native SDK expects a numeric Ezoic ad unit identifier. Pass it as a string in Flutter, for example '12345'.

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.

EzoicBannerView supports these event callbacks:

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

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 Android has a valid domain and iOS has valid apiKey and siteId values.
  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.
  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.