Osmos Flutter Plugin #

Flutter plugin for displaying banner, carousel, interstitial, picture-in-picture, and native ads using OSMOS SDK.

📚 Documentation #

For complete integration guides and API documentation, see:

• Getting Started - Initial setup and prerequisites
• Ad Fetching - How to fetch ads using the plugin
• Ad Rendering - Overview of ad rendering capabilities
• Banner Ads - Displaying banner ads
• Carousel Ads - Implementing carousel ad views
• Interstitial Ads - Full-screen interstitial ads
• Picture-in-Picture Ads - PiP video ad implementation
• Native Ads - Native ad integration
• Native Ad Carousel - Carousel of native ads
• PDA Ad Integration - Product Display Ad integration
• Event Registration - Tracking and analytics
• Changelog - Release notes and version history

For Plugin Maintainers #

• Release and Handover Guide - Complete guide for publishing to pub.dev and managing native SDKs

Features #

• 🎯 Display Ads - Sponsored display ads with flexible targeting
• 🛍️ Product Ads - Sponsored product ads for e-commerce (PLA and PDA)
• 🎨 Multiple Ad Formats - Banner, carousel, interstitial, PiP, native ads, and multi-ad carousel
• 📹 Native Video Support - Video rendering in carousel and native ads
• 👁️ OMID Tracking - Industry-standard viewability measurement
• 🏷️ Custom Ad Labels - Configurable ad disclosure labels with alignment options
• 🎥 Video Quartile Events - Detailed video playback tracking (0%, 25%, 50%, 75%, 100%)
• 📊 Event Tracking - Comprehensive analytics and event registration
• 🔄 Batch Event Processing - Reliable event tracking with offline support (Android)
• ⚡ Async/Await - Modern Dart async patterns
• 🔧 Flexible Configuration - Global or on-demand SDK instances
• 📱 Cross-Platform - Supports both iOS and Android

Quick Start #

Installation #

Add osmos_flutter_plugin to your project's pubspec.yaml file:

dependencies:
  osmos_flutter_plugin:
    path: path/to/osmos_flutter_plugin

Basic Usage #

import 'package:osmos_flutter_plugin/core/osmos_sdk.dart';

// Initialize SDK (typically in main.dart or app initialization)
void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Create global SDK instance
  await OsmosSDK.clientId("your_client_id_here")
      .debug(true)
      .buildGlobalInstance();

  runApp(MyApp());
}

// Use SDK anywhere in your app
class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final osmosSDK = OsmosSDK.globalInstance();

    // Access SDK components
    final adFetcher = osmosSDK.adFetcher;
    final bannerAdView = osmosSDK.bannerAdView;

    return Scaffold(
      body: Column(
        children: [
          // Your content here
        ],
      ),
    );
  }
}

Requirements #

• Flutter SDK: Version 3.3.0 or higher (Built and tested with Flutter 3.27.1)
• Dart SDK: Version 3.6.0 or higher
• iOS: iOS 16.0 or later
• Android: API 23 (Android 6.0) or later

Platform-Specific Setup #

iOS Setup #

1. Set minimum deployment target to iOS 16.0 in your app's ios/Podfile:

platform :ios, '16.0'

Android Setup #

1. Set minimum SDK version in your app's android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 23
        compileSdkVersion 35
    }
}

2. Add internet permission to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Updating Native SDKs #

This plugin bundles the native Osmos SDKs for both iOS and Android. If you need to update or replace these SDKs with newer versions, follow the instructions below.

Current SDK Versions #

• iOS: osmos.xcframework (located in ios/Frameworks/)
• Android: osmos-sdk-v2.0.2.jar (located in android/libs/)

Updating iOS SDK #

The iOS SDK is bundled as an XCFramework. To replace it:

1. Locate the current framework:

   ios/Frameworks/osmos.xcframework/
   

2. Replace with new version:

   • Delete the existing osmos.xcframework folder
   • Copy your new osmos.xcframework into ios/Frameworks/

3. Verify the configuration:

   • Open ios/osmos_flutter_plugin.podspec
   • Ensure this line points to the correct framework:

     s.vendored_frameworks = 'Frameworks/osmos.xcframework'
     

4. Clean and rebuild:

   flutter clean
   cd ios && pod install && cd ..
   flutter run
   

Updating Android SDK #

The Android SDK is bundled as a JAR file. To replace it:

1. Locate the current JAR:

   android/libs/osmos-sdk-v2.0.2.jar
   

2. Replace with new version:

   • Delete or rename the existing JAR file (e.g., osmos-sdk-v2.0.2.jar)
   • Copy your new JAR file into android/libs/
   • Note the exact filename of your new JAR

3. Update the build configuration:

   • Open android/build.gradle
   • Update the filename in the dependencies section:

     dependencies {
         // Update this line with your new JAR filename
         implementation (files("libs/osmos-sdk-v2.0.2.jar"))
         // ... other dependencies
     }
     

4. Clean and rebuild:

   flutter clean
   flutter pub get
   flutter run
   

Verification #

After updating either SDK:

1. Run your app on the target platform (iOS/Android)
2. Verify that ads load and display correctly
3. Check for any runtime errors in the console
4. Test all ad formats your app uses (banner, native, interstitial, etc.)

Troubleshooting #

iOS Issues:

• If the framework is not found, verify the path in osmos_flutter_plugin.podspec
• Clean derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
• Re-run pod install: cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

Android Issues:

• If the JAR is not found, verify the filename matches exactly in build.gradle
• Clean Android build: cd android && ./gradlew clean && cd ..
• Invalidate caches in Android Studio: File → Invalidate Caches / Restart

License #

See LICENSE file for details.