Docs
SDKsFlutter

Changelog

Version history and release notes for the Flutter SDK.

Version 1.0.0 (September 15, 2026)

1.0.0 is now stable and no longer in beta. Update your dependency to the stable release. Upgrading from 0.x? Follow the migration guide.

Version 1.0.0-beta.1 (August 25, 2026)

First release of the 1.0 line — a major, breaking upgrade from the 0.x series, published as a beta on pub.dev; pin the exact version. The 1.0 API is frozen. The full 0.x → 1.0 upgrade path is in the migration guide.

Highlights

  • Visitor attributes. New setAge(int) / setAgeRange(KoahAgeRange), setGender(KoahGender), and setIncomeBracket(KoahIncomeBracket) on Koah share anonymous demographic signals for targeting; values persist locally and .unknown clears the device-stored value. Under-13 ages are rejected. See Visitor Attributes.
  • Per-axis slot sizing. Every KoahCard constructor takes width and height parameters of the new sealed KoahAxisSize type (fixed / range / fill; null = unbounded). A served ad that can't fit a forced or capped height renders nothing (zero size, no impression) and emits the new SlotTooSmall event instead of clipping, and ad fetches are now size-gated and debounced so a slot only requests what it can render.
  • Real User-Agent. Ad requests now send a real user agent. Flutter traffic previously resolved to no OS and no device type, which excluded it from device-targeted ad groups — Flutter inventory is now fully targetable.
  • Expandable ad format. KoahCard now renders the expandable format; preview it with KoahPreviewFormat.expandableMd or the KoahSampleAd.samples.expandable specimen.
  • InAppBrowserClosed event. onEvent now reports when the visitor closes the in-app browser opened by an ad click. To report this first-party on iOS, the package is now a Flutter plugin with a small iOS native component — iOS hosts pick up the pod on their next build. Other platforms are unaffected.
  • Sturdier ad parsing. An ad image arriving without pixel dimensions no longer drops the entire ad — the card renders with a default aspect ratio instead.

Breaking changes

  • KoahCard(adContext: ...) is now the unnamed constructor: KoahCard.withContext is removed, along with the legacy KoahCard(query:, messageId:, queryResponse:, conversationId:) constructor and its four public fields.
  • KoahCard.fromCache(messageId: ...) → KoahCard.fromCache(cacheKey: ...).
  • The legacy imperative trio Koah.prefetch / Koah.resolveAd / Koah.cancelPrefetch and the legacy Koah.process are removed — use prefetchAd(adContext: ..., cacheKey: ...) / requestAd / cancelPrefetchAd(cacheKey).
  • KoahAdLoader is removed — pair prefetchAd with KoahCard.fromCache(cacheKey: ...) instead.
  • overrideMaxWidth / overrideMaxHeight are removed — pass width / height: KoahAxisSize.range(max: ...) instead.
  • KoahAdResult is reshaped from a filled flag into the sealed cases KoahAdFilled / KoahAdNoFill / KoahAdError; the format field is gone.
  • KoahLogLevel is reshaped to none / error / warning / info / debug — verbose is gone (use debug).
  • KoahAdSize and the deprecated size: parameters are removed; KoahPreviewFormat cases are now render formats (cardTextMd, cardImageMd, pollMd, pollCtaMd, expandableMd).
  • Koah.trackPollVoted is removed — poll votes are recorded automatically.
  • Minimum Flutter is 3.29.2 (the SDK requires Dart ^3.7.2).

Version 0.1.3 (June 23, 2026)

Highlights

  • Ad disclaimers. When an ad carries disclaimer text, KoahCard now shows an info (ⓘ) affordance next to the "Sponsored" caption that opens a disclaimer bottom sheet. Surfaced on the model as the new nullable KoahAd.disclaimer; the affordance renders automatically with no integration changes.
  • Decoupled from flutter_secure_storage's API surface. Device-ID persistence now goes through an internal KoahSecureStore abstraction (with an injectable seam on Koah.instance), so plugin API churn across flutter_secure_storage majors no longer ripples into the SDK. Builds on 0.1.2's widened dependency ranges.

Improvements

  • /client/info uploads are debounced. Device info is now uploaded only when its fingerprint changes since the last successful send, instead of on every launch — fewer redundant network calls.

Version 0.1.2 (June 12, 2026)

Highlights

  • Widened plugin dependency ranges. device_info_plus now allows >=11.0.0 <14.0.0, flutter_secure_storage >=9.2.4 <11.0.0, and package_info_plus >=8.0.0 <11.0.0, so apps already on the latest plugin majors can resolve koah_flutter without dependency_overrides. Lower bounds are unchanged — existing resolutions are unaffected, and apps pinned to older plugin majors (e.g. for Android minSdk < 23) keep resolving exactly as before.
  • Embedded pub.dev example. A minimal chat-style KoahCard.withContext integration now ships in example/ and renders on the package's Example tab.

Version 0.1.1 (June 2, 2026)

Highlights

  • Docs-only patch. Corrects the pubspec.yaml dependency snippet in the pub.dev README (was stale at ^0.0.1). No SDK behavior changes from 0.1.0.

Version 0.1.0 (May 29, 2026)

Highlights

  • Unified requestAd API (v2). New Koah.instance.requestAd(adContext:, size:, cacheKey:), Koah.instance.prefetchAd(...), and Koah.instance.cancelPrefetchAd(cacheKey) post to a new /ad_requests endpoint that uses a discriminated KoahAdContext (Conversation / Article / Feed / Static) for matching, copy selection, and format eligibility — same shape as iOS, Android, and React Native. The new KoahCard.withContext(adContext:, size:, cacheKey:, ...) constructor takes the context directly. Migration: KoahCard(query:, messageId:, ...) still works against the legacy /query path but emits deprecation warnings; new code should adopt KoahCard.withContext(...).
  • Prefetch / resolveAd primitives for feeds. Koah.instance.prefetchAd(...) + KoahCard.fromCache(messageId:) let feed integrations warm a slot ahead of render and resolve it later when the cell scrolls into view. Avoids the "first frame is empty" problem in long feeds.
  • requestPreviewAd for publisher format previews. New Koah.instance.requestPreviewAd(previewFormat:) returns a deterministic sample creative for a given format (small / medium / expandable / poll), so publishers can wire their preview UIs without depending on live fill.
  • Poll ad format. Interactive multi-choice prompt with server-tracked option events and a clickable CTA with animated reveal. Matches the web SDK contract; renders inside KoahCard automatically when the server returns a poll creative.
  • Ad report flow. New Icons.more_horiz affordance on the ad caption opens a showModalBottomSheet half-sheet (About this ad → Report this ad → submit) that posts to POST /k/report. No new public exports.
  • KoahTheme minimal styling API (breaking). Replaces KoahCardStyle and KoahCardOptions with a 4-knob KoahTheme applied via KoahThemeProvider. Knobs: colorScheme (KoahColorScheme.light / .dark / .auto), accentColor (defaults to #0D0D0D, text-on-accent auto-contrasted via WCAG luminance), fontFamily (null inherits from the host app), and cornerRadius. KoahColorScheme.auto resolves via MediaQuery.platformBrightnessOf and re-resolves automatically when the device theme flips. Matches iOS / Android / React Native exactly. See the Flutter SDK page for the full migration mapping.
  • chrome: parameter for borderless embedding. New chrome: KoahCardChrome.standard (default — surface background, 0.5dp border, padding, rounded radius) / KoahCardChrome.bare (inline content; host surface owns the chrome) on every KoahCard constructor. Mirrors iOS's KoahCard(chrome: .bare) and Android's KoahAd composable.
  • KoahCard visual refresh. Layout, spacing, typography, and image treatment now match the latest cross-platform design (parity with iOS, Android, and React Native).
  • Optional slot parameter. requestAd / prefetchAd now accept an optional slot: String? that surfaces in matching and reporting. Lets a single page tag multiple distinct ad placements without colliding on the cache key or muddying analytics.
  • Optional experimentTag. New experimentTag: String? parameter on requestAd / prefetchAd is forwarded with every ad request, letting publishers split-test creatives or surface variants without piggy-backing on the cache key.
  • BoxFit.contain on KoahAdImage. Ad images now match the iOS / Android / RN aspect-ratio treatment instead of cropping.

Improvements

  • Production-key debug warning. When debug = true but the configured publisherId looks like a production key, the SDK logs a clear warning on no-fill so integrators don't silently think their staging setup is broken.
  • Strict medium card size constraints. KoahCardOptions.size is enforced as a hard match against the server's ad.size. The SDK also declares its supportedFormats on every ad request, so the server only returns formats this client can render.
  • /client/info superset. Flutter joins iOS, Android, and React Native on the unified device-info payload — locale, timezone, screen metrics, etc. — so backend personalization decisions are consistent across platforms.
  • Keychain failure tolerance. AuthManager no longer hard-fails when flutter_secure_storage is unavailable (e.g. on emulators with locked-down keychains); device IDs fall back to in-memory generation for the session.
  • V2 ad_type no longer crashes on unsupported formats. Wire payloads with formats this version doesn't render now degrade gracefully (dropped + logged) instead of throwing.
  • adText removed from publisher-facing fill events. Tracking events no longer leak ad copy to the publisher's analytics surface.

Note on versioning

This is the first 0.1.x Flutter release. Earlier 0.0.x versions were pre-feature-flow groundwork and added no new SDK surface. Future Flutter releases follow a 0.x.y semver rubric.

Was this helpful?