Yodo SDK Flutter Plugin

A Flutter plugin that integrates Yodo1's Managed Ad Services (MAS) SDK, providing a simple way to display ads in your Flutter applications on both Android and iOS platforms.

📋 Table of Contents

Features
Installation
Platform Setup
Quick Start
Implementation Guide
Ad Types
Best Practices
Error Handling
Troubleshooting
API Reference

✨ Features

✅ Interstitial Ads - Full-screen ads shown between content
✅ Rewarded Ads - Users watch ads to earn rewards
✅ Rewarded Interstitial Ads - Combination of interstitial and rewarded ads
✅ App Open Ads - Ads shown when the app is opened
✅ Banner Ads - Small ads displayed at the top or bottom of the screen
✅ Native Ads - Customizable ads that match your app's design
✅ Privacy Compliance - Built-in support for GDPR, CCPA, and COPPA
✅ Placement IDs - Support for custom placement IDs
✅ Preloading - Option to preload ads for better performance

📦 Installation

Step 1: Add the dependency

Add yodosdk to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  yodosdk: ^1.0.8

Step 2: Install the package

Run the following command in your terminal:

flutter pub get

Step 3: Import the package

In your Dart files, import the package:

import 'package:yodosdk/yodosdk.dart';

🔧 Platform Setup

Android Setup

Minimum SDK Version: Ensure your android/app/build.gradle has:
```
minSdkVersion 21
```
Internet Permission: Add internet permission to android/app/src/main/AndroidManifest.xml:
```
<uses-permission android:name="android.permission.INTERNET"/>
```
ProGuard Rules (if using ProGuard): Add to android/app/proguard-rules.pro:
```
-keep class com.yodo1.** { *; }
-dontwarn com.yodo1.**
```

iOS Setup

Minimum iOS Version: Ensure your ios/Podfile has:
```
platform :ios, '11.0'
```

Info.plist: Add the following to ios/Runner/Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

Install Pods: Run:
```
cd ios
pod install
```

🚀 Quick Start

Step 1: Get Your App ID

Sign up at Yodo1 MAS Dashboard
Create a new app
Copy your App ID

Step 2: Initialize the SDK

Initialize the SDK in your app's main file (usually main.dart):

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

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _initializeSDK();
  }

  Future<void> _initializeSDK() async {
    await Yodosdk.initSdk(
      appId: "YOUR_APP_ID_HERE", // Replace with your actual App ID
      preLoadAds: true, // Preload ads for better performance
      showPrivacyDialog: true, // Show privacy dialog to users
      coppa: false, // Set to true if your app targets children
      gdpr: true, // Set GDPR compliance
      ccpa: false, // Set CCPA compliance
      initAdCallback: InitAdCallback(
        onSuccess: () {
          print("✅ SDK initialized successfully!");
          // You can now show ads
        },
        onError: (error) {
          print("❌ SDK initialization failed: $error");
          // Handle initialization error
        },
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      home: HomeScreen(),
    );
  }
}

Important Notes:

Replace "YOUR_APP_ID_HERE" with your actual Yodo App ID
Always initialize the SDK before showing any ads
The onSuccess callback means the SDK is ready to use
Handle errors in the onError callback

📖 Implementation Guide

Understanding Callbacks

Callbacks are functions that get called when something happens with an ad. Think of them as notifications:

onLoad: The ad finished loading and is ready to show
onAdLoadFail: The ad failed to load (maybe no internet or no ads available)
onAdOpen: The ad was opened/shown to the user
onAdOpenFail: Failed to show the ad
onClose: The user closed the ad
onRewardEarned: (For reward ads) The user earned a reward

1. Interstitial Ads

Interstitial ads are full-screen ads shown between content (like between game levels).

When to use: Between screens, after completing a task, between game levels

import 'package:yodosdk/yodosdk.dart';

// In your widget or function
void _showInterstitialAd() {
  Yodosdk.loadAndShowInter(
    placementId: "your_placement_id", // Optional: Use custom placement ID
    fullScreenAdCallbacks: FullScreenAdCallbacks(
      onLoad: (adId) {
        print("✅ Interstitial ad loaded: $adId");
        // Ad is ready to show
      },
      onAdLoadFail: (error) {
        print("❌ Interstitial ad failed to load: $error");
        // Handle error - maybe show a message or retry
      },
      onAdOpen: (adId) {
        print("📱 Interstitial ad opened: $adId");
        // Pause your game/app here
      },
      onAdOpenFail: (error) {
        print("❌ Interstitial ad failed to open: $error");
        // Handle error
      },
      onClose: (adId) {
        print("👋 Interstitial ad closed: $adId");
        // Resume your game/app here
        // Give rewards or continue to next level
      },
    ),
  );
}

// Example: Show ad after completing a level
void _onLevelComplete() {
  // Show congratulations message
  _showCongratulations();

  // Show interstitial ad
  _showInterstitialAd();

  // After ad closes, continue to next level
}

2. Rewarded Ads

Rewarded ads let users watch an ad to earn a reward (like extra lives, coins, etc.).

When to use: When user wants extra lives, bonus coins, skip a level, etc.

void _showRewardedAd() {
  Yodosdk.loadAndShowReward(
    placementId: "reward_placement", // Optional
    rewardAdCallbacks: RewardAdCallbacks(
      onLoad: (adId) {
        print("✅ Reward ad loaded: $adId");
      },
      onAdLoadFail: (error) {
        print("❌ Reward ad failed to load: $error");
        // Show message: "Ad not available, please try again later"
      },
      onAdOpen: (adId) {
        print("📱 Reward ad opened: $adId");
        // Pause your app
      },
      onAdOpenFail: (error) {
        print("❌ Reward ad failed to open: $error");
      },
      onClose: (adId) {
        print("👋 Reward ad closed: $adId");
        // Note: User might not have watched the full ad
        // Only give reward if onRewardEarned was called
      },
      onRewardEarned: (adId) {
        print("🎉 Reward earned! Ad ID: $adId");
        // Give reward here (extra lives, coins, etc.)
        _giveReward();
      },
    ),
  );
}

void _giveReward() {
  // Add coins, extra lives, etc.
  setState(() {
    coins += 100;
    lives += 1;
  });

  // Show success message
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text("You earned 100 coins and 1 extra life!")),
  );
}

// Example: Button to watch ad for extra life
ElevatedButton(
  onPressed: () {
    _showRewardedAd();
  },
  child: Text("Watch Ad for Extra Life"),
)

Important: Only give rewards when onRewardEarned is called, not just when the ad closes!

3. Rewarded Interstitial Ads

Similar to rewarded ads but shown as full-screen interstitials.

void _showRewardedInterstitialAd() {
  Yodosdk.loadAndShowRewardInter(
    rewardAdCallbacks: RewardAdCallbacks(
      onLoad: (adId) => print("✅ Rewarded interstitial loaded"),
      onAdLoadFail: (error) => print("❌ Failed: $error"),
      onAdOpen: (adId) => print("📱 Ad opened"),
      onAdOpenFail: (error) => print("❌ Failed to open: $error"),
      onClose: (adId) => print("👋 Ad closed"),
      onRewardEarned: (adId) {
        print("🎉 Reward earned!");
        _giveReward();
      },
    ),
  );
}

4. App Open Ads

Ads shown when the app is opened (like when user returns to the app).

When to use: When app starts or when user returns from background

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _initializeSDK();
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) {
      // User returned to the app
      _showAppOpenAd();
    }
  }

  void _showAppOpenAd() {
    Yodosdk.loadAndShowAppOpen(
      fullScreenAdCallbacks: FullScreenAdCallbacks(
        onLoad: (adId) => print("✅ App open ad loaded"),
        onAdLoadFail: (error) => print("❌ Failed: $error"),
        onAdOpen: (adId) => print("📱 App open ad shown"),
        onAdOpenFail: (error) => print("❌ Failed to open: $error"),
        onClose: (adId) => print("👋 App open ad closed"),
      ),
    );
  }
}

Small ads displayed at the top or bottom of the screen.

When to use: On main screens, game menus, etc.

import 'package:yodosdk/yodosdk.dart';

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("My App")),
      body: Column(
        children: [
          // Your app content here
          Expanded(
            child: Center(child: Text("Your App Content")),
          ),

          // Banner ad at the bottom
          Yodosdk.getBanner(
            size: BannerSize.adaptiveBanner, // Adapts to screen width
            bannerAdCallback: BannerAdCallback(
              onLoad: () {
                print("✅ Banner ad loaded");
              },
              onLoadFailed: (error) {
                print("❌ Banner ad failed: $error");
              },
              onOpen: () {
                print("📱 Banner ad clicked");
              },
              onOpenFail: (error) {
                print("❌ Banner ad click failed: $error");
              },
              onClosed: () {
                print("👋 Banner ad closed");
              },
            ),
          ),
        ],
      ),
    );
  }
}

Banner Sizes Available:

BannerSize.banner - Standard banner (320x50)
BannerSize.largeBanner - Large banner (320x100)
BannerSize.adaptiveBanner - Adapts to screen width (recommended)
BannerSize.smartBanner - Smart banner (full width, 50px height)
BannerSize.iabMediumRectangle - Medium rectangle (300x250)

6. Native Ads

Customizable ads that match your app's design.

When to use: In lists, feeds, or custom layouts

Yodosdk.getNative(
  size: NativeSize.nativeLarge, // or NativeSize.nativeSmall
  nativeAdCallback: NativeAdCallback(
    onLoad: () {
      print("✅ Native ad loaded");
    },
    onLoadFailed: (error) {
      print("❌ Native ad failed: $error");
    },
    onClosed: () {
      print("👋 Native ad closed");
    },
  ),
)

Native Sizes:

NativeSize.nativeSmall - Small native ad (300x100)
NativeSize.nativeLarge - Large native ad (600x335)

💡 Best Practices

1. Initialize Once

Initialize the SDK only once, preferably in your main() function or app initialization:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  _initializeSDK(); // Initialize here
  runApp(MyApp());
}

2. Preload Ads

Enable preLoadAds: true during initialization to preload ads for better performance:

await Yodosdk.initSdk(
  appId: "YOUR_APP_ID",
  preLoadAds: true, // Preload ads
  // ...
);

3. Show Ads at Appropriate Times

Interstitial Ads: Between levels, after completing tasks, between screens
Rewarded Ads: When user wants extra lives, coins, or bonuses
Banner Ads: On main screens, menus, or content screens
App Open Ads: When app starts or resumes from background

4. Handle Errors Gracefully

Always handle errors in callbacks:

onAdLoadFail: (error) {
  // Don't show error to user, just log it
  print("Ad failed: $error");

  // Optionally show a friendly message
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text("Ad not available right now")),
  );
}

5. Don't Spam Ads

Don't show ads too frequently
Give users time between ads
Consider user experience

6. Test on Real Devices

Always test on real devices, not just simulators/emulators.

⚠️ Error Handling

Common Errors and Solutions

1. SDK Initialization Failed

Error: SDK initialization failed

Possible Causes:

Invalid App ID
No internet connection
SDK not properly configured

Solution:

initAdCallback: InitAdCallback(
  onSuccess: () {
    print("SDK ready!");
  },
  onError: (error) {
    print("Init error: $error");
    // Check your App ID
    // Check internet connection
    // Check platform setup
  },
),

2. Ad Failed to Load

Error: Ad failed to load

Possible Causes:

No ads available
No internet connection
Ad not ready yet

Solution:

onAdLoadFail: (error) {
  // Log the error
  print("Ad load failed: $error");

  // Don't show error to user
  // Optionally retry after a delay
  Future.delayed(Duration(seconds: 5), () {
    _showAdAgain(); // Retry showing ad
  });
}

3. Ad Failed to Open

Error: Ad failed to open

Possible Causes:

Ad was closed before it could open
Network issues
Ad expired

Solution:

onAdOpenFail: (error) {
  print("Ad open failed: $error");
  // Try loading a new ad
  _loadNewAd();
}

🔍 Troubleshooting

Problem: Ads not showing

Checklist:

✅ Is SDK initialized? (Check onSuccess callback)
✅ Is your App ID correct?
✅ Do you have internet connection?
✅ Are you testing on a real device?
✅ Is your app properly configured in Yodo1 dashboard?
✅ Are you calling the ad methods after SDK initialization?

Problem: Ads showing but callbacks not working

Solution:

Make sure you're setting callbacks before calling loadAndShow* methods
Check that callbacks are not null
Verify method channel names match

Problem: App crashes when showing ads

Solution:

Check platform setup (Android/iOS configuration)
Verify minimum SDK versions
Check for null pointer exceptions in callbacks
Review error logs

Problem: Privacy dialog not showing

Solution:

Ensure showPrivacyDialog: true in initialization
Check platform-specific privacy settings
Verify Info.plist (iOS) or AndroidManifest.xml (Android)

📚 API Reference

Yodosdk Class

`initSdk()`

Initializes the Yodo SDK.

Parameters:

appId (String, required) - Your Yodo App ID
preLoadAds (bool, default: false) - Preload ads for better performance
showPrivacyDialog (bool, default: true) - Show privacy dialog
coppa (bool, default: false) - COPPA compliance
gdpr (bool, default: true) - GDPR compliance
ccpa (bool, default: false) - CCPA compliance
initAdCallback (InitAdCallback, required) - Initialization callbacks

`loadAndShowInter()`

Loads and shows an interstitial ad.

Parameters:

fullScreenAdCallbacks (FullScreenAdCallbacks, required) - Ad event callbacks
placementId (String?, optional) - Custom placement ID

`loadAndShowReward()`

Loads and shows a rewarded ad.

Parameters:

rewardAdCallbacks (RewardAdCallbacks, required) - Ad event callbacks
placementId (String?, optional) - Custom placement ID

`loadAndShowRewardInter()`

Loads and shows a rewarded interstitial ad.

Parameters:

rewardAdCallbacks (RewardAdCallbacks, required) - Ad event callbacks
placementId (String?, optional) - Custom placement ID

`loadAndShowAppOpen()`

Loads and shows an app open ad.

Parameters:

fullScreenAdCallbacks (FullScreenAdCallbacks, required) - Ad event callbacks
placementId (String?, optional) - Custom placement ID

`getBanner()`

Creates a banner ad widget.

Parameters:

bannerAdCallback (BannerAdCallback, required) - Ad event callbacks
size (BannerSize, default: BannerSize.largeBanner) - Banner size

Returns: Widget

`getNative()`

Creates a native ad widget.

Parameters:

nativeAdCallback (NativeAdCallback, required) - Ad event callbacks
size (NativeSize, default: NativeSize.nativeSmall) - Native ad size

Returns: Widget

`showPrivacyDialog()`

Shows the privacy dialog.

Callback Classes

`InitAdCallback`

onSuccess() - Called when SDK initializes successfully
onError(String? error) - Called when initialization fails

`FullScreenAdCallbacks`

onLoad(String? adId) - Called when ad loads
onAdLoadFail(String? error) - Called when ad fails to load
onAdOpen(String? adId) - Called when ad opens
onAdOpenFail(String? error) - Called when ad fails to open
onClose(String? adId) - Called when ad closes

`RewardAdCallbacks`

onLoad(dynamic adId) - Called when ad loads
onAdLoadFail(dynamic error) - Called when ad fails to load
onAdOpen(dynamic adId) - Called when ad opens
onAdOpenFail(dynamic error) - Called when ad fails to open
onClose(dynamic adId) - Called when ad closes
onRewardEarned(dynamic adId) - Called when user earns reward

`BannerAdCallback`

onLoad() - Called when banner loads
onLoadFailed(String errorMessage) - Called when banner fails to load
onOpen() - Called when banner is clicked
onOpenFail(String error) - Called when banner click fails
onClosed() - Called when banner is closed

`NativeAdCallback`

onLoad() - Called when native ad loads
onLoadFailed(String errorMessage) - Called when native ad fails to load
onClosed() - Called when native ad is closed

📞 Support

Email: Devloperrb73375@gmail.com

📄 License

See LICENSE file for details.

🙏 Contributing

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

Made with ❤️ for Flutter developers

Yodo SDK Flutter Plugin

📋 Table of Contents

✨ Features

📦 Installation

Step 1: Add the dependency

Step 2: Install the package

Step 3: Import the package

🔧 Platform Setup

Android Setup

iOS Setup

🚀 Quick Start

Step 1: Get Your App ID

Step 2: Initialize the SDK

📖 Implementation Guide

Understanding Callbacks

1. Interstitial Ads

2. Rewarded Ads

3. Rewarded Interstitial Ads

4. App Open Ads

5. Banner Ads

6. Native Ads

💡 Best Practices

1. Initialize Once

2. Preload Ads

3. Show Ads at Appropriate Times

4. Handle Errors Gracefully

5. Don't Spam Ads

6. Test on Real Devices

⚠️ Error Handling

Common Errors and Solutions

1. SDK Initialization Failed

2. Ad Failed to Load

3. Ad Failed to Open

🔍 Troubleshooting

Problem: Ads not showing

Problem: Ads showing but callbacks not working

Problem: App crashes when showing ads

Problem: Privacy dialog not showing

📚 API Reference

Yodosdk Class

initSdk()

loadAndShowInter()

loadAndShowReward()

loadAndShowRewardInter()

loadAndShowAppOpen()

getBanner()

getNative()

showPrivacyDialog()

Callback Classes

InitAdCallback

FullScreenAdCallbacks

RewardAdCallbacks

BannerAdCallback

NativeAdCallback

📞 Support

📄 License

🙏 Contributing

Libraries

yodosdk package

`initSdk()`

`loadAndShowInter()`

`loadAndShowReward()`

`loadAndShowRewardInter()`

`loadAndShowAppOpen()`

`getBanner()`

`getNative()`

`showPrivacyDialog()`

`InitAdCallback`

`FullScreenAdCallbacks`

`RewardAdCallbacks`

`BannerAdCallback`

`NativeAdCallback`