Audienzz SDK Flutter #

Overview #

A mobile advertising SDK that combines header bidding capabilities from Prebid Mobile with Google's advertising ecosystem through a unified interface. The implementation includes lazy loading functionality to optimize application performance by deferring ad initialization until needed.

Underlying Technologies #

Prebid Mobile SDK #

Prebid Mobile is an open-source framework that enables header bidding within mobile applications. It conducts real-time auctions where multiple demand sources compete for ad inventory placement.

Functionality:

• Real-time auction management between demand partners
• Communication with Prebid Server for bid processing
• Support for banner, native, and video ad formats
• Ad rendering from winning auction results

Google Ads SDK (Google Mobile Ads SDK) #

The Google Mobile Ads SDK provides access to Google's advertising networks including AdMob and Google Ad Manager. It handles ad serving and mediation across multiple ad networks.

Functionality:

• Banner, interstitial, native, and rewarded video ad formats
• Network mediation through Google's platform
• Performance analytics and reporting
• Privacy compliance features

Minimum Supported Versions #

The Audienzz Flutter SDK requires a minimum iOS version of 13.0 or higher and a minimum android version of API 24 (Android 7.0, Nougat) or higher.

Installation #

In your terminal run command:

flutter pub add audienzz_sdk_flutter

OR add directly to pubspec.yaml

    audienzz_sdk_flutter: latest

and run command:

flutter pub get

Setup Android #

Add your AdMob app ID, to your app's AndroidManifest.xml file. To do so, add a

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Setup IOS #

Update your app's Info.plist file with your AdMob app ID:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

Initialize SDK #

First of all, SDK needs to be initialized. It's done asynchronously, so after callback is triggered with InitializationStatus.success, SDK is ready to be used.

 final status = await AudienzzSdkFlutter.instance.initialize(companyId: 'CompanyID', isAutomaticPpidEnabled: false);

 if (status == InitializationStatus.success) {
   // SDK is ready to be used
 }

CompanyId is provided by Audienzz, usually - it is id of the company in ad console. Automatic PPID (Publisher Provided Identifier for Google Ad Manager) usage could be specified at initialization or though PpidManager class.

The Audienzz SDK Flutter allows you to display three types Ads - BannerAd, InterstitialAd and RewardedAd.

Examples #

You can find examples of practical implementation here:

Examples

Quick Start #

Minimal initialization and first ad load.

import 'package:audienzz_sdk_flutter/audienzz_sdk_flutter.dart';
import 'package:flutter/material.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final status = await AudienzzSdkFlutter.instance
      .initialize(companyId: 'YOUR_COMPANY_ID');
  runApp(MyApp(initialized: status == InitializationStatus.success));
}

class MyApp extends StatefulWidget {
  const MyApp({super.key, required this.initialized});
  final bool initialized;

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  BannerAd? _banner;

  @override
  void initState() {
    super.initState();
    _banner = BannerAd(
      adUnitId: 'YOUR_AD_UNIT_ID',
      auConfigId: 'YOUR_AU_CONFIG_ID',
      sizes: {const AdSize(width: 320, height: 50)},
      onAdLoaded: (_) => debugPrint('Banner loaded'),
      onAdFailedToLoad: (_, error) => debugPrint('Banner load failed: ${error?.message}'),
    )..load();
  }

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Audienzz Quick Start')),
        body: widget.initialized && _banner != null
            ? Center(child: AdWidget(ad: _banner!))
            : const Center(child: Text('SDK not initialized')),
      ),
    );
  }
}

Interstitial minimal usage #

final interstitial = InterstitialAd(
  adUnitId: 'YOUR_AD_UNIT_ID',
  auConfigId: 'YOUR_AU_CONFIG_ID',
  adFormat: AdFormat.bannerAndVideo,
  onAdLoaded: (_) => debugPrint('Interstitial loaded'),
  onAdFailedToLoad: (_, error) => debugPrint('Interstitial fail: ${error?.message}'),
  onAdClosed: (ad) async {
    await ad.dispose();
  },
);
await interstitial.load();
await interstitial.show();

Rewarded minimal usage #

final rewarded = RewardedAd(
  adUnitId: 'YOUR_AD_UNIT_ID',
  auConfigId: 'YOUR_AU_CONFIG_ID',
  onAdLoaded: (_) => debugPrint('Rewarded loaded'),
  onAdFailedToLoad: (_, error) => debugPrint('Rewarded fail: ${error?.message}'),
  onUserEarnedRewardCallback: (_, reward) {
    debugPrint('User rewarded: ${reward.amount} ${reward.type}');
  },
  onAdClosed: (ad) async {
    await ad.dispose();
  },
);
await rewarded.load();
await rewarded.show();

Remote Configuration Integration #

The SDK supports a simplified integration using remote configuration. This allows you to manage ad units (GAM IDs, Prebid Config IDs, sizes, etc.) from the backend, requiring only a simple configuration ID in your app.

Initialize SDK with Remote Configuration #

Before using remote configuration ads, ensure the SDK is properly initialized:

final status = await AudienzzSdkFlutter.instance.initializeRemote(
  publisherId: 'YOUR_PUBLISHER_ID', // Will be provided for you
  remoteUrl: 'https://dev-api.adnz.co/api/ws-sdk-config/public/v1/', // Audienzz remove config URL
  isAutomaticPpidEnabled: false
);

if (status == InitializationStatus.success) {
  // SDK is ready to use with remote config
}

Banner Ad (Remote Config) #

Use RemoteBannerAd to load a banner defined by a remote configuration ID.

// 1. Create the remote banner ad with the configuration ID
final remoteBanner = RemoteBannerAd(
  configId: 'YOUR_CONFIG_ID',
  onAdLoaded: (ad) {
    debugPrint('Remote banner loaded successfully');
  },
  onAdFailedToLoad: (ad, error) {
    debugPrint('Remote banner failed to load: ${error?.message}');
  },
  onAdClicked: (ad) {
    debugPrint('Remote banner clicked');
  },
  onAdClosed: (ad) {
    debugPrint('Remote banner closed');
  },
);

// 2. Load the ad
await remoteBanner.load();

#### Fixed Size Banner
The SDK will use the sizes defined in the remote configuration. To ensure the banner is displayed correctly, you should place the `AdWidget` inside a container (like a `SizedBox`) that matches the intended ad size:

```dart
Center(
  child: SizedBox(
    width: 320,
    height: 50,
    child: AdWidget(ad: remoteBanner),
  ),
)

Adaptive Banner

If adaptive banners are enabled in the backend for your configuration ID, the SDK will automatically calculate the optimal height. You should ensure the AdWidget has enough horizontal space to calculate the adaptive size correctly:

Center(
  child: AdWidget(ad: remoteBanner),
)

// 3. Display the ad using AdWidget @override Widget build(BuildContext context) { return Center( child: AdWidget(ad: remoteBanner), ); }

// 4. Dispose when done @override void dispose() { remoteBanner.dispose(); super.dispose(); }

## Interstitial Ad (Remote Config)

Use `RemoteInterstitialAd` to load an interstitial defined by a remote configuration ID.

```dart
// 1. Create the remote interstitial ad with the configuration ID
final remoteInterstitial = RemoteInterstitialAd(
  configId: 'YOUR_CONFIG_ID',
  onAdLoaded: (ad) {
    debugPrint('Remote interstitial loaded successfully');
  },
  onAdFailedToLoad: (ad, error) {
    debugPrint('Remote interstitial failed to load: ${error?.message}');
  },
  onAdClosed: (ad) async {
    debugPrint('Remote interstitial closed');
    await ad.dispose();
  },
);

// 2. Load the ad
await remoteInterstitial.load();

// 3. Show the ad when ready
await remoteInterstitial.show();

Targeting basics #

Set per-user data (keywords, location, privacy) and global targeting.

User keywords #

await AudienzzTargeting.addUserKeywords(['sports', 'travel']);
await AudienzzTargeting.addUserKeyword('gaming');
final all = await AudienzzTargeting.getKeywordSet();
await AudienzzTargeting.removeUserKeyword('travel');
await AudienzzTargeting.clearUserKeywords();

User location #

await AudienzzTargeting.setUserLatLng(47.3769, 8.5417); // Zurich
final loc = await AudienzzTargeting.getUserLatLng();

GDPR / COPPA #

await AudienzzTargeting.setSubjectToGDPR(isSubject: true);
await AudienzzTargeting.setGdprConsentString('COabcd...');
await AudienzzTargeting.setPurposeConsents('111000');
await AudienzzTargeting.setSubjectToCOPPA(isSubject: false);

External User IDs (EIDs) #

await AudienzzTargeting.setExternalUserIds([
  ExternalUserId(
    source: 'adserver.org',
    uniqueIds: [UniqueId(id: 'user-123', atype: 1)],
  ),
]);
final eids = await AudienzzTargeting.getExternalUserIds();

Global targeting and ext data #

// Global key -> single value
await AudienzzTargeting.addSingleGlobalTargeting('section', 'home');

// Global key -> multiple values
await AudienzzTargeting.addGlobalTargeting('interests', {'tech', 'finance'});

// Remove / Clear
await AudienzzTargeting.removeGlobalTargeting('section');
await AudienzzTargeting.clearGlobalTargeting();

// Ext data
await AudienzzTargeting.addExtData('category', 'news');
await AudienzzTargeting.updateExtData('tags', ['flutter', 'ads']);
await AudienzzTargeting.removeExtData('category');
await AudienzzTargeting.clearExtData();

Global OpenRTB config #

await AudienzzTargeting.setGlobalOrtbConfig({
  'regs': {
    'coppa': 0,
  },
  'user': {
    'yob': 1990,
  },
});
final ortb = await AudienzzTargeting.getGlobalOrtbConfig();

Passing placement identifiers on ads #

final banner = BannerAd(
  adUnitId: 'YOUR_AD_UNIT_ID',
  auConfigId: 'YOUR_AU_CONFIG_ID',
  sizes: {const AdSize(width: 320, height: 50)},
  pbAdSlot: '/1234/home/top_banner',
  gpId: 'gpid-abc-123',
  impOrtbConfig: '{"ext":{"example":"value"}}', // custom ORTB at imp-level
  onAdLoaded: (_) {},
  onAdFailedToLoad: (_, __) {},
)..load();

PpidManager #

API Reference #

SDK Initialization #

Ad Base Classes #

Ad #

AdWithView (extends Ad) #

AdWithoutView (extends Ad) #

BannerAd (extends AdWithView) #

InterstitialAd (extends AdWithoutView) #

RewardedAd (extends AdWithoutView) #

AdWidget #

Data Classes & Enums #

AdFormat #

AdSize #

ApiParameter #

Placement #

PlaybackMethod #

Protocol #

VideoBitrate #

VideoDuration #

MinSizePercentage #

AdError #

RewardItem #

InitializationStatus #

Exceptions #

License #

Copyright 2025 Audienzz AG.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.