XMediator Flutter SDK

Flutter plugin for XMediator SDK - Cross-platform ad mediation.

Installation

Add to your pubspec.yaml:

dependencies:
  xmediator_flutter: ^0.1.0

Or via Git:

dependencies:
  xmediator_flutter:
    git:
      url: https://github.com/x3mads/xmediator-flutter.git
      ref: v0.1.0

Platform Setup

Android

Add the XMediator Maven repository to your project's android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://android-artifact-registry.x3mads.com/maven" }
    }
}

Ensure minimum SDK is 21:

android {
    defaultConfig {
        minSdk 21
    }
}

iOS

Add the XMediator CocoaPods source to your ios/Podfile:

source 'https://github.com/x3mads/podspecs.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '12.0'

Then run:

cd ios && pod install

Quick Start

Start the SDK

import 'package:xmediator_flutter/xmediator_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await XMediatorAds.startWith(
    'YOUR_APP_KEY',
    settings: InitSettings(
      testMode: true,
      verbose: true,
    ),
    onInitialized: (result) {
      if (result.success) {
        // Load ads after successful initialization
        XMediatorAds.interstitial.load('your_placement_id');
        XMediatorAds.rewarded.load('your_placement_id');
      }
    },
  );
  
  runApp(MyApp());
}

Interstitial Ads

// Add listener
XMediatorAds.interstitial.addListener(MyInterstitialListener());

// Load
await XMediatorAds.interstitial.load('your_placement_id');

// Check if ready (specific placement)
if (await XMediatorAds.interstitial.isReady('your_placement_id')) {
  // Show with ad space tracking
  await XMediatorAds.interstitial.show(
    placementId: 'your_placement_id',
    adSpace: 'main_menu',
  );
}

// Or check if ANY interstitial is ready and show any available
if (await XMediatorAds.interstitial.isReady()) {
  await XMediatorAds.interstitial.show(); // Shows any available ad
}

// Check ad space capping
if (!await XMediatorAds.interstitial.isAdSpaceCapped('main_menu')) {
  // Ad space is not capped, safe to show
}

Rewarded Ads

// Add listener to handle rewards
class MyRewardedListener extends RewardedAdsListener {
  @override
  void onRewarded(String placementId) {
    // Grant the reward to the user
    print('User earned reward!');
  }
  
  @override
  void onLoaded(String placementId, LoadResult result) {
    print('Ad loaded: ${result.success}');
  }
}

XMediatorAds.rewarded.addListener(MyRewardedListener());

// Load
await XMediatorAds.rewarded.load('your_placement_id');

// Show with ad space tracking
if (await XMediatorAds.rewarded.isReady('your_placement_id')) {
  await XMediatorAds.rewarded.show(
    placementId: 'your_placement_id',
    adSpace: 'level_complete',
  );
}

// Or show any available rewarded ad
if (await XMediatorAds.rewarded.isReady()) {
  await XMediatorAds.rewarded.show();
}

BannerAdWidget(
  placementId: 'your_banner_placement',
  size: BannerSize.phone,
)

Programmatic Banners

// Create and load
await XMediatorAds.banner.create('your_placement_id', size: BannerSize.phone);
await XMediatorAds.banner.load('your_placement_id');

// Set ad space for tracking (optional)
await XMediatorAds.banner.setAdSpace('your_placement_id', 'home_screen');

// Show at position
await XMediatorAds.banner.show(
  'your_placement_id',
  position: BannerPosition.bottomCenter,
);

// Hide
await XMediatorAds.banner.hide('your_placement_id');

// Destroy when done
await XMediatorAds.banner.destroy('your_placement_id');

BannerAds.show(...) anchors the banner to the host window and always applies safe-area insets (notches, home indicator, system bars).

Available BannerPosition anchors: topLeft, topCenter, topRight, centerLeft, centered, centerRight, bottomLeft, bottomCenter, bottomRight.

Use either BannerAdWidget or programmatic show(...) per placement at a time. They should not be active simultaneously for the same placement ID.

App Open Ads

XMediatorAds.appOpen.addListener(MyAppOpenListener());

// Load
await XMediatorAds.appOpen.load('your_placement_id');

// Show (typically on app resume)
if (await XMediatorAds.appOpen.isReady('your_placement_id')) {
  await XMediatorAds.appOpen.show(
    placementId: 'your_placement_id',
    adSpace: 'app_launch',
  );
}

// Or show any available app open ad
if (await XMediatorAds.appOpen.isReady()) {
  await XMediatorAds.appOpen.show();
}

User Properties & Consent

Set User Properties

XMediatorAds.setUserProperties(UserProperties(
  userId: 'user123',
  purchaseSummary: PurchaseSummary(
    totalAmountSpent: 9.99,
    currencyCode: 'USD',
  ),
));

XMediatorAds.setConsentInformation(ConsentInformation(
  hasUserConsent: true,
  isDoNotSell: false,
  isChildDirected: false,
));

CMP Provider

// Check if privacy form is available
if (XMediatorAds.cmpProvider.isPrivacyFormAvailable()) {
  // Show privacy form
  final error = await XMediatorAds.cmpProvider.showPrivacyForm();
  if (error != null) {
    print('Error showing privacy form: ${error.message}');
  }
}

Event Tracking

XMediatorAds.eventTracker.trackPurchase(PurchaseEvent(
  amount: 4.99,
  currency: 'USD',
  sku: 'com.myapp.coins100',
  name: '100 Coins Pack',
));

XMediatorAds.eventTracker.trackAppEvent(
  AppEvent.standard(AppEventName.levelComplete),
);

// Ad opportunity tracking (track BEFORE readiness/capping checks)
XMediatorAds.eventTracker.trackAdOpportunity(
  AdOpportunityEvent.interstitial('level_complete'),
);

Debugging

Open the debugging suite to inspect ad configurations:

XMediatorAds.openDebuggingSuite();
Size Dimensions Usage
BannerSize.phone 320x50 Phone banner
BannerSize.tablet 728x90 Tablet leaderboard
BannerSize.mrec 300x250 Medium rectangle

API Reference

XMediatorAds

Method Description
startWith(appKey, settings, onInitialized) Start the SDK
openDebuggingSuite() Open debugging UI
isInitialized Check if SDK is initialized
getUserProperties() Get current user properties
setUserProperties(properties) Set user properties
getConsentInformation() Get consent info
setConsentInformation(info) Set consent info

Fullscreen Ads (Interstitial, Rewarded, App Open)

Method Description
load(placementId) Load an ad for the placement
isReady([placementId]) Check if ad is ready (specific or any)
isAdSpaceCapped(adSpace) Check if ad space is capped
show({placementId, adSpace}) Show ad with optional parameters
addListener(listener) Add event listener
removeListener(listener) Remove event listener
Method Description
create(placementId, {size}) Create a banner
load(placementId) Load the banner
isReady(placementId) Check if banner is ready
show(placementId, {position}) Show the banner at an anchor position
hide(placementId) Hide the banner
setAdSpace(placementId, adSpace) Set ad space for tracking
destroy(placementId) Destroy the banner

Services

  • XMediatorAds.cmpProvider - CMP/Privacy
  • XMediatorAds.eventTracker - Event tracking

License

MIT License - see LICENSE for details.

Libraries

xmediator_flutter