flutter_ads_orchestrator 0.1.0

Smart AdMob orchestration for Flutter apps: preload, throttle, caps, placement rules, UMP consent. Supports interstitial and rewarded ads.

Changelog

All notable changes to this project are documented here. Format follows Keep a Changelog; versioning follows Semantic Versioning.

0.1.0 — Unreleased

Initial release. Built and tested against google_mobile_ads ^8.0.0.

Added

• AdsOrchestrator: one entry point that wires AdMob loaders, UMP consent, daily/session/cooldown state, fallback chain, and the rule evaluator.
• AdsConfig / InterstitialRules / RewardedRules / ConsentConfig / RetryPolicy — immutable, const-constructible configuration.
• Smart preload with exponential-backoff retry and a fallback ad-unit chain (PreloadManager).
• Throttling primitives: CooldownTracker, SessionCounter, TriggerCounter, DailyCounter (SharedPreferences-backed with local-midnight rollover).
• Declarative placement rules: PlacementRule.allowed, PlacementRule.disabled, PlacementRule.triggerEvery(N) — interstitial-only; rewarded silently ignores.
• App-open guard for interstitials after cold start.
• UMP consent integrated via AdMobConsentManager; NoOpConsentManager for tests / regions without consent requirements.
• iOS ATT hook (ConsentConfig.attRequestCallback) — caller supplies the ATT plugin.
• Sealed result types: ShowResult (AdShown / AdSuppressed / AdShowFailed / AdNotReady) and AdError (LoadError / ShowError / TimeoutError / DisposedError / ConsentError).
• Typed SuppressionReason with 10 cases.
• Event stream (AdEvent sealed with 10 subtypes) for analytics integration.
• Test mode: testMode: true auto-overrides production unit IDs with Google's official test IDs per platform.
• Global controls: setNoAdsFlag (persisted), resetSessionCounters (test-only), showPrivacyOptions, resetConsent.
• Example app demonstrating every placement rule, rewarded flow, no-ads toggle, and privacy form (in example/).

Tests

• 181 unit / integration tests covering all 10 suppression reasons, retry/backoff, fallback chain, expiration auto-reload, concurrent-show protection, dispose mid-flight, and rewarded reward callbacks.
• 100% line coverage on the pure-Dart layer (rules, counters, preload, orchestrator). The AdMob/UMP wrappers (AdMobInterstitialAdLoader, AdMobRewardedAdLoader, AdMobConsentManager) are structurally type-checked but require device smoke testing before production rollout.

Known limitations

• Debug overlay deferred to v0.2.
• App-lifecycle observer (resume-pause-detached) deferred to v0.2; the cold-start guard works today via the initialise timestamp.
• Per-placement caps deferred to v0.2.
• Banner / native / app-open full implementations deferred to v0.2 – v0.4.
• AdMob/UMP wrappers built against google_mobile_ads 8.0.0 API surfaces but not exercised on real devices in this release — see PUBLISH_CHECKLIST.md for smoke-test steps.