JustBaat Ads Flutter Plugin - Production Implementation Guide #

Overview #

This guide will help you integrate the JustBaat Ads Flutter plugin into your production Flutter application. The plugin provides a Flutter-compatible wrapper for the JustBaat Ads SDK, enabling you to display ads from Google AdMob and Unity Ads networks.

Quick Start - Production Setup #

For production apps, use the Maven repository setup:

1. Add Maven repository in settings.gradle or settings.gradle.kts:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://justbaat-apps-b325d.web.app") }
       }
   }
   

2. Add SDK dependency in app/build.gradle:

   dependencies {
       implementation("com.justbaatAds:adsSdk:1.0.8")
   }
   

3. Add plugin to pubspec.yaml:

   dependencies:
     justbaat_ads:
       path: ../flutter_plugin
   

4. Initialize SDK in your Flutter app (see Step 3 below)

Prerequisites #

• Flutter SDK: >=3.0.0
• Android: minSdk 21, compileSdk 35
• Android Gradle Plugin: 8.6.0+
• Kotlin: 2.1.0+
• JustBaat Ads SDK: Version 1.0.8+ (available via Maven repository)

Step 1: Add Plugin to Your Flutter Project #

1.1 Update pubspec.yaml #

Add the plugin as a dependency:

dependencies:
  flutter:
    sdk: flutter
  justbaat_ads: ^1.0.0

1.2 Install Dependencies #

flutter pub get

Step 2: Configure Android Project #

2.1 Update android/settings.gradle (or settings.gradle.kts) #

For Production (Using Maven Repository):

If using Groovy (settings.gradle):

pluginManagement {
    def flutterSdkPath = {
        def properties = new Properties()
        file("local.properties").withInputStream { properties.load(it) }
        def flutterSdkPath = properties.getProperty("flutter.sdk")
        assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
        return flutterSdkPath
    }()

    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")

    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.6.0" apply false
    id "com.android.library" version "8.6.0" apply false
    id "org.jetbrains.kotlin.android" version "2.1.0" apply false
    id "org.jetbrains.kotlin.plugin.compose" version "2.1.0" apply false
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://justbaat-apps-b325d.web.app") }
    }
}

include ":app"

// Note: Flutter plugin is auto-discovered, no need to include it manually
// SDK is fetched from Maven repository, not included as a project module

If using Kotlin DSL (settings.gradle.kts):

pluginManagement {
    val flutterSdkPath: String = run {
        val properties = java.util.Properties()
        file("local.properties").inputStream().use { properties.load(it) }
        val flutterSdkPath = properties.getProperty("flutter.sdk")
            ?: throw GradleException("flutter.sdk not set in local.properties")
        flutterSdkPath
    }

    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")

    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0" apply false
    id("com.android.application") version "8.6.0" apply false
    id("com.android.library") version "8.6.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.0" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.1.0" apply false
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://justbaat-apps-b325d.web.app") }
    }
}

include(":app")

2.2 Update android/app/build.gradle (or build.gradle.kts) #

For Production (Using Maven Repository):

If using Groovy (build.gradle):

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.0"
    // SDK from Maven repository
    implementation("com.justbaatAds:adsSdk:1.0.8")
}

If using Kotlin DSL (build.gradle.kts):

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.0")
    // SDK from Maven repository
    implementation("com.justbaatAds:adsSdk:1.0.8")
}

2.3 Configure android/app/src/main/AndroidManifest.xml #

Add required permissions and AdMob Application ID:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Required permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application
        android:label="Your App Name"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        tools:replace="android:label">

        <!-- AdMob Application ID (REQUIRED) -->
        <!-- Replace with your actual AdMob App ID for production -->
        <!-- Test ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-3940256099942544~3347511713" />

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">
            <!-- ... rest of activity config ... -->
        </activity>
    </application>
</manifest>

⚠️ Important: Replace the test AdMob App ID with your production App ID from your AdMob account.

Step 3: Initialize the SDK in Your Flutter App #

3.1 Basic Initialization #

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

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

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

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

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    
    // Initialize SDK after first frame
    WidgetsBinding.instance.addPostFrameCallback((_) {
      _initializeSdk();
    });
  }

  void _initializeSdk() async {
    try {
      // Wait for activity to be ready
      await Future.delayed(const Duration(milliseconds: 500));
      
      if (!mounted) return;
      
      await JustbaatAds.initialize(
        companyId: 'your-company-id',  // Replace with your company ID
        onSdkReady: () {
          print('JustBaat Ads SDK is ready!');
          // SDK is initialized and ready to use
        },
      );
    } catch (e, stackTrace) {
      print('Error initializing SDK: $e');
      print('Stack trace: $stackTrace');
      // Handle initialization error
    }
  }

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

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // Required: Notify SDK when app resumes
    if (state == AppLifecycleState.resumed) {
      JustbaatAds.onActivityResumed();
    }
  }

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

Key Points:

• ✅ Always call JustbaatAds.onActivityResumed() in didChangeAppLifecycleState
• ✅ Initialize SDK after the first frame using addPostFrameCallback
• ✅ Wait 500ms before initialization to ensure Activity is ready
• ✅ Handle errors gracefully

Step 4: Implement Ad Types #

4.1 Banner Ads #

Banner ads are displayed as widgets in your Flutter UI:

import 'package:justbaat_ads/justbaat_ads.dart';

BannerAdWidget(
  divId: 'banner_container_first',  // Must match your config.json
  height: 50,  // Height in logical pixels
  onAdLoaded: () {
    print('Banner ad loaded successfully!');
  },
  onAdFailed: (error) {
    print('Banner ad failed: $error');
  },
)

4.2 Interstitial Ads #

// Load the ad first
JustbaatAds.loadInterstitial(
  placementId: 'interstitial_placement',  // Must match your config.json
  onAdLoaded: () {
    print('Interstitial ad loaded!');
    // Now you can show it
  },
  onAdFailed: (error) {
    print('Interstitial failed to load: $error');
  },
);

// Show the ad (call after loading)
JustbaatAds.showInterstitial(
  placementId: 'interstitial_placement',
  enableClickCounting: true,  // Track clicks
  threshold: 1,  // Minimum clicks before showing
  onAdDismissed: () {
    print('Interstitial ad dismissed');
    // User closed the ad
  },
  onAdFailed: (error) {
    print('Interstitial failed to show: $error');
  },
);

4.3 Rewarded Ads #

// Load the ad
JustbaatAds.loadRewarded(
  placementId: 'rewarded_placement',  // Must match your config.json
  onAdLoaded: () {
    print('Rewarded ad loaded!');
  },
  onAdFailed: (error) {
    print('Rewarded failed to load: $error');
  },
);

// Show the ad
JustbaatAds.showRewarded(
  placementId: 'rewarded_placement',
  enableClickCounting: true,
  threshold: 5,  // Minimum clicks before showing
  onUserEarnedReward: (reward) {
    print('Reward earned: ${reward.amount} ${reward.type}');
    // Give reward to user
  },
  onAdDismissed: () {
    print('Rewarded ad dismissed');
  },
  onAdFailedToShow: (error) {
    print('Rewarded failed to show: $error');
  },
);

4.4 Native Ads #

Native ads are displayed as widgets:

NativeAdWidget(
  divId: 'native_ad_container',  // Must match your config.json
  height: 300,  // Height in logical pixels
  onAdLoaded: () {
    print('Native ad loaded!');
  },
  onAdFailed: (error) {
    print('Native ad failed: $error');
  },
)

4.5 App Open Ads #

// Load the ad (typically done during app initialization)
JustbaatAds.loadAppOpen(
  onAdLoaded: () {
    print('App Open ad loaded!');
  },
  onAdFailed: (error) {
    print('App Open failed to load: $error');
  },
);

// Show the ad (typically when app opens)
JustbaatAds.showAppOpen(
  onAdDismissed: () {
    print('App Open ad dismissed');
  },
  onAdFailedToShow: () {
    print('App Open failed to show');
  },
);

Configuration Requirements: #

1. Company ID: Must match the companyId passed to JustbaatAds.initialize()
2. divId: For Banner and Native ads, must match the divId in your widgets
3. placementId: For Interstitial and Rewarded ads, must match the placementId in your code
4. Ad Unit IDs: Configured in your config.json for each ad network (Google AdMob, Unity Ads)

Step 6: Important Notes #

6.1 Cache Behavior #

• ✅ Fixed: Each companyId now has its own cache (fixed in latest version)
• ✅ Cache duration: 24 hours
• ✅ Cache is stored in SharedPreferences: ad_config_prefs
• ⚠️ Important: If you change companyId, the SDK will fetch fresh config for that company

6.2 Activity Lifecycle #

• ✅ Always implement WidgetsBindingObserver in your main app widget
• ✅ Always call JustbaatAds.onActivityResumed() when app resumes
• ✅ This is required for proper ad lifecycle management

6.3 Error Handling #

Always handle errors gracefully:

try {
  await JustbaatAds.initialize(companyId: 'your-id', onSdkReady: () {});
} catch (e) {
  // Log error, show user-friendly message, or use fallback
  print('SDK initialization failed: $e');
}

6.4 Testing #

• Use test AdMob App ID during development: ca-app-pub-3940256099942544~3347511713
• Use test ad unit IDs from AdMob console
• Test on real devices (not just emulators)
• Test with different network conditions

Step 7: Troubleshooting #

Issue: App crashes on startup #

Solution:

1. Check if AdMob App ID is added to AndroidManifest.xml
2. Verify companyId is correct
3. Check logcat: adb logcat | grep -E "(JustbaatAdsPlugin|AdSdkManager|AndroidRuntime)"

Issue: Ads not loading #

Solution:

1. Verify divId/placementId matches your config.json
2. Check network connectivity
3. Verify ad unit IDs are correct in config.json
4. Check logcat for specific error messages

Issue: Wrong ads showing for different companyId #

Solution:

• This was fixed in the latest version
• Each companyId now has its own cache
• Clear app data or wait for cache to expire (24 hours)

Issue: Build errors #

Solution:

1. Ensure Android Gradle Plugin is 8.6.0+
2. Ensure Kotlin version is 2.1.0+
3. Ensure SDK module is included in settings.gradle
4. Run flutter clean and rebuild

Step 8: Production Checklist #

Before releasing to production:

• ❌ Replace test AdMob App ID with production App ID
• ❌ Replace test ad unit IDs with production ad unit IDs
• ❌ Verify all divId and placementId values match config.json
• ❌ Test all ad types on real devices
• ❌ Test with different network conditions
• ❌ Verify error handling works correctly
• ❌ Test app lifecycle (background/foreground)
• ❌ Verify ads comply with AdMob policies
• ❌ Test with your actual companyId
• ❌ Monitor ad performance in AdMob console

Step 9: Example Complete Implementation #

See flutter_plugin/example for a complete working example with all ad types implemented.

Support #

For issues or questions:

1. Check logcat for error messages
2. Verify configuration matches this guide
3. Test with the example app first
4. Review BRIDGE_VERIFICATION.md for bridge status

Version Information #

• Plugin Version: 1.0.0
• SDK Version: Latest (from sdk/ module)
• Flutter Support: >=3.0.0
• Android Support: minSdk 21+

Last Updated: January 2025

Make sure your ad configuration is properly set up on the server with the correct divId and placementId values.

Example #

See the example/ directory for a complete example app.

License #

MIT License

Copyright (c) 2026 JustBaat

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.