osmos_flutter_plugin #

Overview #

osmos_flutter_plugin is a Flutter plugin built for OSMOS Ad Fetching, Ad Rendering and Event Tracking. It is designed to be lightweight, efficient, and easy to integrate into any Flutter application.

Features #

• Ad fetching capabilities
• Advanced ad rendering
• Comprehensive event tracking
• Cross-platform support for Android and iOS ``

Requirements #

• Flutter SDK: Version 3.3.0 or higher
• Dart SDK: Version 3.6.0 or higher
• Supported Platforms: Android, iOS

Installation #

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

dependencies:
  osmos_flutter_plugin: ^2.0.1

Then run:

flutter pub get

Usage #

1. Initialize the SDK #

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

// Initialize OSMOS SDK globally
await OsmosSDK.clientId("your_client_id")
    .debug(true) // Enable debug mode for development
    .productAdsHost("your-product-ads-host") // Optional: PLA server
    .displayAdsHost("your-display-ads-host") // Optional: Display ads server
    .eventTrackingHost("your-event-tracking-host") // Optional: Event tracking server
    .buildGlobalInstance();

// Get the global SDK instance
OsmosSDK sdk = OsmosSDK.globalInstance();

2. Fetch Ads #

// Fetch display ads with targeting parameters
import 'package:osmos_flutter_plugin/models/targetingParams.dart';

var context = ContextTargeting.keyword("your_keyword");
var geo = GeoTargeting.location(city: "city", country: "country");

var response = await sdk.adFetcher.fetchDisplayAdsWithAu(
    cliUbid: "user_id",
    pageType: "page_type",
    productCount: 10,
    adUnits: ["banner_ads"],
    targetingParams: [context, geo]
);

// Fetch banner ads for rendering
var adData = await sdk.adRenderer.fetchBannerAdsWithAu(
    cliUbid: "user_id",
    pageType: "page_type",
    adUnit: "banner_ads"
);

3. Display Ads #

// Display banner ad
sdk.bannerAdView.showAd(
    adData: adData,
    height: 120,
    width: double.infinity,
    onAdClick: (data) {
        // Handle ad click
    },
    onViewAppeared: (data, url) {
        // Handle ad impression
    },
);

// Display interstitial ad
await sdk.interstitialAdView.showAd(
    adData: adData,
    alignment: "center"
);

4. Track Events #

import 'package:osmos_flutter_plugin/models/trackingParams.dart';

// Build tracking parameters
var params = TrackingParams.builder()
    .videoViewSec(4)
    .skuId("product_sku")
    .build();

// Register ad click event
await sdk.registerEvent.registerAdClickEvent(
    cliUbid: "user_id",
    uclid: "unique_content_id",
    trackingParams: params,
);

API Reference #

Core Classes #

• OsmosSDK - Main SDK class for initialization and accessing managers
• OsmosSDK.Builder - Builder pattern for SDK configuration

Manager Interfaces #

• adFetcher - Fetch display ads with targeting parameters
• adRenderer - Render ads for display
• registerEvent - Track and register ad events
• bannerAdView - Manage banner ad displays
• carouselAdView - Manage carousel ad displays
• interstitialAdView - Manage interstitial ad displays
• multiAdCarouselView - Manage multi-ad carousel displays
• pipAdView - Manage picture-in-picture ad displays

Key Methods #

SDK Initialization

• OsmosSDK.clientId(String) - Set client ID
• Builder.debug(bool) - Enable/disable debug mode
• Builder.buildGlobalInstance() - Create global SDK instance

Ad Fetching

• adFetcher.fetchDisplayAdsWithAu() - Fetch display ads with targeting
• adRenderer.fetchBannerAdsWithAu() - Fetch banner ads for rendering

Ad Display

• bannerAdView.showAd() - Display banner ads
• interstitialAdView.showAd() - Display interstitial ads

Event Tracking

• registerEvent.registerAdClickEvent() - Track ad click events

Example #

See the example/ directory for a complete sample application demonstrating how to use this plugin.

Platform Support #

License #

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

Contributing #

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support #

For support, please visit https://www.osmos.ai/ or open an issue on GitHub.