SDKsFlutter

Migrate to 1.0

Move a 0.x koah_flutter integration to the 1.0 API: renamed card constructors, per-axis sizing, and a sealed result type.

Koah Flutter 1.0 is a hard break with no compatibility shims. Apps on 0.x keep working against the 0.x releases, but upgrading the package requires the code changes below. Most call sites change only a few lines — or copy the prompt below and let a coding agent migrate for you.

Prompt for coding agents

I use Koah's Flutter SDK (the koah_flutter package) on a 0.x version. Migrate my integration to the 1.0 API. Read https://docs.koahlabs.com/sdk/flutter/migration and follow its instructions.

What changes

Aspect	0.x	1.0
Card constructor	`KoahCard.withContext(adContext: ...)`	The unnamed `KoahCard(adContext: ...)`
Legacy query constructor	`KoahCard(query:, messageId:, ...)`	Removed. Build a `KoahAdContext` instead.
Warmed slots	`KoahCard.fromCache(messageId: ...)`	`KoahCard.fromCache(cacheKey: ...)`
Imperative fetch	`prefetch`, `resolveAd`, `cancelPrefetch`, `process`	`prefetchAd`, `requestAd`, `cancelPrefetchAd`
`KoahAdLoader`	Prefetch-and-observe helper	Removed. Pair `prefetchAd` with `KoahCard.fromCache`.
Sizing	`overrideMaxWidth` / `overrideMaxHeight: int?`	`width` / `height: KoahAxisSize` (`null` = unbounded)
Result	`KoahAdResult` with a `filled` flag	Sealed: `KoahAdFilled` / `KoahAdNoFill` / `KoahAdError`
Logging	`KoahLogLevel.verbose`	`KoahLogLevel.debug` (`warning` and `info` are new)
Format previews	`KoahAdSize` + `KoahPreviewFormat.cardText`, ...	`KoahAdSize` removed; `KoahPreviewFormat.cardTextMd`, ...
Poll tracking	`Koah.trackPollVoted(...)`	Removed. Votes are recorded automatically.
Toolchain	Flutter `>=1.17.0`	Flutter `>=3.29.2` (Dart `^3.7.2`, unchanged)

Rename the card constructors

KoahCard.withContext is now the unnamed constructor, and KoahCard.fromCache takes cacheKey instead of messageId. Behavior is unchanged.

KoahCard.withContext(
  adContext: KoahAdContext.conversation(
    question: userMessage,
    answer: aiResponse,
  ),
  cacheKey: 'msg-1',
)

KoahCard.fromCache(messageId: 'msg-1')

Replace the legacy query constructor

The deprecated unnamed KoahCard(query:, messageId:, ...) constructor — and the legacy /query path behind it — is gone. Describe the surrounding content with a KoahAdContext and pass the old messageId as cacheKey.

KoahCard(
  query: userMessage,
  queryResponse: aiResponse,
  messageId: 'msg-1',
)

A 0.x conversationId becomes externalConversationId on KoahAdContext.conversation(...).

Replace the imperative trio

Koah.prefetch, Koah.resolveAd, and Koah.cancelPrefetch (positional query strings) become prefetchAd, requestAd, and cancelPrefetchAd (named parameters with a KoahAdContext). Koah.process is also removed — request with requestAd and render with a KoahCard. KoahAdLoader is removed too: pair prefetchAd with KoahCard.fromCache(cacheKey: ...).

await Koah.instance().prefetch(userMessage, aiResponse, 'msg-1');
final state = await Koah.instance().resolveAd(userMessage, aiResponse, 'msg-1');
Koah.instance().cancelPrefetch('msg-1');

resolveAd returned a KoahAdState; requestAd returns a KoahAdResult — switch over its sealed cases (below).

Move to per-axis sizing

The max-only overrideMaxWidth / overrideMaxHeight knobs become width and height, each a KoahAxisSize built with a factory constructor: KoahAxisSize.fixed(dp), KoahAxisSize.range(min: ..., max: ...) (either bound may be omitted), or KoahAxisSize.fill(). null (the default) leaves the axis unbounded. Units are logical pixels, as before.

KoahCard.withContext(
  adContext: adContext,
  cacheKey: 'msg-1',
  overrideMaxWidth: 384,
  overrideMaxHeight: 320,
)

KoahAxisSize.fill() requires a parent that bounds that axis. A fill axis inside an axis the parent leaves unbounded (like the scroll axis of a scroller) throws a FlutterError at the slot's first layout — deterministically, before any ad is fetched — so the misconfiguration surfaces during development.

A served ad that can't fit a fixed or capped height renders nothing (zero size) and emits a SlotTooSmall event instead of clipping. No impression is tracked for a de-rendered card. See Sizing.

Switch over the sealed result

KoahAdResult is now a sealed class with three cases instead of a filled flag; its format field is gone.

final result = await Koah.instance().requestAd(
  adContext: adContext,
  cacheKey: 'msg-1',
);
if (result.filled) {
  // ad available to render
}

Update log levels

KoahLogLevel is reshaped from none / error / verbose to none / error / warning / info / debug. Replace verbose with debug; none stays the default.

Koah.instance(
  publisherId: 'your-publisher-id',
  logLevel: KoahLogLevel.verbose,
);

Update preview formats

KoahAdSize and the deprecated size: parameters are removed — bound the slot with width / height on the card, or dimensions: KoahDimensions(maxWidth: ..., maxHeight: ...) on the imperative calls. KoahPreviewFormat cases are now render formats:

0.x	1.0
`cardText`	`cardTextMd`
`cardImage`	`cardImageMd`
`poll`	`pollMd`
—	`pollCtaMd` (new)
`expandable`	`expandableMd`
`rabbitHole`	Removed

Handle the new events

Not a rename, but it will surface as a compile error: KoahEvent gains two subclasses — InAppBrowserClosed and SlotTooSmall — so an exhaustive switch over KoahEvent without a wildcard must add the new cases. See Event handling.

Koah.trackPollVoted is removed with no replacement — poll votes are recorded automatically when the visitor taps an option.

Install 1.0

Update your pubspec.yaml to the stable release:

dependencies:
  koah_flutter: ^1.0.0

koah_flutter is now a Flutter plugin with a small iOS native component, so in an iOS app run pod install in your ios/ directory after upgrading (a plain flutter run also does this for you).

Need help upgrading? Email support@koahlabs.com.