multi_ads_sdk 1.0.9 copy "multi_ads_sdk: ^1.0.9" to clipboard
multi_ads_sdk: ^1.0.9 copied to clipboard

Published 36 hours ago • Latest: 1.0.10
SDKFlutter
PlatformAndroidiOS
→

Metadata

A comprehensive Flutter SDK for multi-provider ads (AdMob, AdX, Facebook) with single-load and single-show pattern. Built with clean architecture principles and supports Android & iOS.

More...

multi_ads_sdk #

pub package

A comprehensive Flutter SDK for multi-provider ads (AdMob, AdX, Facebook) with single-load and single-show pattern. Built with clean architecture principles and supports Android & iOS.

Features #

  • ✅ Multi-Provider Support: AdMob, AdX, and Facebook Audience Network
  • ✅ Single-Load & Single-Show Pattern: Only one instance of each ad type in memory
  • ✅ Clean Architecture: Core → Data → Platform layers
  • ✅ Dynamic Ad Unit IDs: Pass ad unit IDs at runtime
  • ✅ Multiple Ad Formats: App Open, Banner, Interstitial, Rewarded, Rewarded Interstitial, Native
  • ✅ Platform Support: Android (Kotlin) & iOS (Swift)
  • ✅ MethodChannel Communication: Efficient native bridge
  • ✅ Error Handling: Comprehensive error handling and callbacks

📋 Features #

  • Multi-Provider Support: AdMob, AdX, and Facebook Audience Network
  • Single-Load & Single-Show Pattern: Only one instance of each ad type in memory
  • Clean Architecture: Core → Data → Platform layers
  • Multiple Ad Formats:
    • App Open Ads
    • Banner Ads (inline + adaptive)
    • Interstitial Ads
    • Rewarded Ads
    • Rewarded Interstitial Ads
    • Native Ads
  • Platform Support: Android (Kotlin) & iOS (Swift)
  • MethodChannel Communication: Efficient native bridge
  • Error Handling: Comprehensive error handling and callbacks

🚀 Installation #

Add this package to your pubspec.yaml:

dependencies:
  multi_ads_sdk: ^1.0.9

Then run:

flutter pub get

Or install from the command line:

flutter pub add multi_ads_sdk

📱 Platform Setup #

Android Setup #

  1. Update android/app/build.gradle:
android {
    defaultConfig {
        minSdkVersion 21
    }
}
  1. Update android/app/src/main/AndroidManifest.xml:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <application>
        <!-- Add your AdMob App ID -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX"/>
    </application>
</manifest>
  1. Dependencies (already included in the package):
    • Google Mobile Ads SDK
    • Facebook Audience Network SDK

iOS Setup #

  1. Update ios/Podfile:
platform :ios, '15.0'
  1. Update ios/Runner/Info.plist:

Add your AdMob App ID:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX</string>
  1. Install Pods:
cd ios
pod install
cd ..
  1. Dependencies (already included in the package):
    • Google-Mobile-Ads-SDK (~> 12.0, Firebase 11 compatible)
    • FBAudienceNetwork

💻 Usage #

Basic Initialization #

import 'package:multi_ads_sdk/multi_ads_sdk.dart';

// Initialize with AdMob
await MultiAdsManager.init(AdProviderType.admob);

// Or use AdX
await MultiAdsManager.init(AdProviderType.adx);

// Or use Facebook
await MultiAdsManager.init(AdProviderType.facebook);

Interstitial Ads #

// Load interstitial with your ad unit ID
await MultiAdsManager.loadInterstitial(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show interstitial
await MultiAdsManager.showInterstitial();

Rewarded Ads #

// Load rewarded ad with your ad unit ID
await MultiAdsManager.loadRewarded(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show rewarded ad with reward callback
await MultiAdsManager.showRewarded(
  onReward: () {
    print('User earned reward!');
    // Give reward to user
  },
);

App Open Ads #

// Load app open ad with your ad unit ID
await MultiAdsManager.loadAppOpen(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show app open ad
await MultiAdsManager.showAppOpen();

// Load banner ad with your ad unit ID
await MultiAdsManager.loadBanner(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show banner ad
await MultiAdsManager.showBanner();

Rewarded Interstitial Ads #

// Load rewarded interstitial with your ad unit ID
await MultiAdsManager.loadRewardedInterstitial(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show rewarded interstitial
await MultiAdsManager.showRewardedInterstitial(
  onReward: () {
    print('User earned reward!');
  },
);

Native Ads #

// Load native ad with your ad unit ID
await MultiAdsManager.loadNative(
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show native ad
await MultiAdsManager.showNative();

Advanced Usage #

You can also use the generic methods:

// Load any ad type with your ad unit ID
await MultiAdsManager.load(
  AdType.interstitial,
  adUnitId: 'ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX',
);

// Show any ad type
await MultiAdsManager.show(AdType.rewarded, onReward: () {
  print('Reward earned!');
});

🏗️ Architecture #

The SDK follows Clean Architecture principles:

lib/
├── src/
│   ├── core/              # Domain layer
│   │   ├── ad_provider_type.dart
│   │   ├── ad_type.dart
│   │   └── base_ad_provider.dart
│   ├── data/              # Data layer
│   │   └── platform_ad_service.dart
│   ├── platform/          # Platform implementations
│   │   ├── admob_provider.dart
│   │   ├── adx_provider.dart
│   │   └── facebook_ads_provider.dart
│   └── multi_ads_manager.dart  # Unified API

📝 Single-Load & Single-Show Pattern #

The SDK enforces a strict single-load and single-show pattern:

  1. Load: Only one instance of each ad type is kept in memory
  2. Show: After showing, the ad instance is automatically destroyed
  3. Reload: You can reload the ad after it's been shown

This pattern ensures:

  • Memory efficiency
  • Predictable ad lifecycle
  • No memory leaks from multiple ad instances

🔧 Configuration #

Dynamic Ad Unit IDs #

The SDK now supports dynamic ad unit IDs - you pass them when loading ads. No need to hardcode them in native code!

Simply pass your ad unit ID when calling any load* method:

// AdMob/AdX ad unit ID format: ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX
await MultiAdsManager.loadInterstitial(
  adUnitId: 'ca-app-pub-1234567890123456/1234567890',
);

// Facebook placement ID format: YOUR_PLACEMENT_ID
await MultiAdsManager.loadInterstitial(
  adUnitId: 'YOUR_FACEBOOK_PLACEMENT_ID',
);

This allows you to:

  • Use different ad unit IDs for different ad types
  • Switch ad unit IDs dynamically based on app configuration
  • Easily test with different ad units without code changes

📊 Callbacks #

The SDK provides callbacks for ad events:

  • onAdLoaded: Ad successfully loaded
  • onAdFailedToLoad: Ad failed to load (with error message)
  • onAdShown: Ad is shown
  • onAdDismissed: Ad is dismissed
  • onAdClicked: Ad is clicked
  • onRewarded: User earned reward (for rewarded ads)

These callbacks are automatically logged to the console. You can customize them in MultiAdsManager._setupEventListeners().

🧪 Testing #

Run the example app:

cd example
flutter run

The example app includes:

  • Material 3 UI
  • Buttons for all ad types
  • Provider selection (AdMob/AdX/Facebook)
  • Status messages
  • Console logging

📚 API Reference #

MultiAdsManager #

Main entry point for the SDK.

Static Methods

  • init(AdProviderType type): Initialize the SDK with a provider
  • load(AdType type): Load an ad of the specified type
  • show(AdType type, {Function()? onReward}): Show an ad of the specified type

Shortcut Methods

  • loadInterstitial({required String adUnitId}) / showInterstitial()
  • loadRewarded({required String adUnitId}) / showRewarded({Function()? onReward})
  • loadAppOpen({required String adUnitId}) / showAppOpen()
  • loadBanner({required String adUnitId}) / showBanner()
  • loadRewardedInterstitial({required String adUnitId}) / showRewardedInterstitial({Function()? onReward})
  • loadNative({required String adUnitId}) / showNative()

Enums #

AdProviderType

enum AdProviderType {
  admob,      // Google AdMob
  adx,        // Google AdX
  facebook,   // Facebook Audience Network
}

AdType

enum AdType {
  banner,              // Banner ads
  interstitial,        // Interstitial ads
  rewarded,           // Rewarded ads
  rewardedInterstitial, // Rewarded interstitial ads
  appOpen,            // App open ads
  native,             // Native ads
}

🐛 Troubleshooting #

Android Issues #

  1. Build errors: Ensure minSdkVersion is at least 21
  2. Ad not loading: Check internet permissions in AndroidManifest.xml
  3. Facebook SDK errors: Ensure Facebook SDK is properly initialized

iOS Issues #

  1. Pod install errors: Run pod repo update then pod install
  2. Build errors: Ensure iOS deployment target is 15.0 or higher
  3. Ad not loading: Check Info.plist for AdMob App ID
  4. Firebase compatibility: This SDK uses Google-Mobile-Ads-SDK 12.x for compatibility with Firebase 11.x. If you see dependency errors:
    • Run cd ios, remove Podfile.lock and Pods, then pod install --repo-update.

📋 Ads failure & exception logging #

The SDK logs ad load failures and exceptions via AdsLogger:

  • Ad failed to load (platform onAdFailedToLoad): logged with ad type and error message.
  • Exceptions (init, load, show, connectivity): logged with message, exception, and stack trace.

In debug mode, all of these are printed to the console. You can set a custom logger (e.g. for Crashlytics) so failures are reported in production:

import 'package:multi_ads_sdk/multi_ads_sdk.dart';

void main() {
  AdsLogger.setLogger((adType, message, [error, stackTrace]) {
    // Send to your crash reporting / analytics
    FirebaseCrashlytics.instance.log('Ad: $adType - $message');
    if (error != null) {
      FirebaseCrashlytics.instance.recordError(error, stackTrace);
    }
  });
  runApp(MyApp());
}

📦 Publishing to pub.dev #

To clear the "2 checked-in files are ignored by .gitignore" warning when running dart pub publish --dry-run, stop tracking those files (they remain on disk and are already in .gitignore):

git rm --cached example/android/local.properties
git rm --cached "example/android/app/src/main/java/io/flutter/plugins/GeneratedPluginRegistrant.java"
git commit -m "chore: stop tracking example Android generated/local files"

Then run dart pub publish --dry-run again; the warning should be gone.

📝 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support #

For issues and questions, please open an issue on GitHub.

Note: This SDK requires you to pass ad unit IDs when loading ads. Use test ad unit IDs during development and replace them with your production ad unit IDs before publishing your app.

← Metadata

1
likes
150
points
318
downloads

Publisher

unverified uploader

Weekly Downloads

Metadata

A comprehensive Flutter SDK for multi-provider ads (AdMob, AdX, Facebook) with single-load and single-show pattern. Built with clean architecture principles and supports Android & iOS.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

flutter

More

Packages that depend on multi_ads_sdk

Packages that implement multi_ads_sdk

Back