Docs
SDKsAndroid

Migrate to 1.0

Replace the legacy query-string calls and deprecated overloads removed in 1.0 with the KoahAdContext-based API.

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 to 1.0 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 Android SDK 0.x (com.koahlabs:koah-android). Migrate my integration to the 1.0 API. Read https://docs.koahlabs.com/sdk/android/migration and follow its instructions.

What changes

Aspect0.x1.0
Imperative fetchprefetch, resolveAd, cancelPrefetch with query / queryResponse / messageIdprefetchAd, requestAd, cancelPrefetchAd with a KoahAdContext and cacheKey
Query-based composablesKoahCard / KoahAd overloads taking query, queryResponse, messageId, conversationId, isResponseReadyOne adContext: KoahAdContext overload per component
SizingDeprecated overrideMaxWidth / overrideMaxHeight overloads with a modifier parameterwidth / height: KoahAxisSize with a padding: PaddingValues parameter
Cache-key parametermessageId on the cache-reading and sample-ad overloadsRenamed to cacheKey. Same value, same behavior.
Fetch resultresolveAd returned a KoahAdStaterequestAd returns a sealed KoahAdResult: Filled, NoFill, or Error

Initialization does not change: Koah(context) { publisherId = "…" } is the same in 0.x and 1.0, and requestAd / prefetchAd / cancelPrefetchAd already existed in 0.3.0 — if you are on them, those call sites carry over unchanged.

Imperative fetch: from query strings to an ad context

Koah.prefetch, Koah.resolveAd, and Koah.cancelPrefetch are removed. Build a KoahAdContext and pass the old messageId as cacheKey:

val state = Koah.instance.resolveAd(
    query = question,
    queryResponse = answer,
    messageId = messageId,
)
if (state is KoahAdState.Filled) { /* render */ }

Koah.instance.prefetch(
    query = question,
    queryResponse = answer,
    messageId = messageId,
)

Koah.instance.cancelPrefetch(messageId)

resolveAd returned a KoahAdState; requestAd returns a sealed KoahAdResult — branch on Filled / NoFill / Error instead. The old conversationId argument becomes externalConversationId on KoahAdContext.Conversation.

Query-based composables: pass an ad context

The KoahCard / KoahAd overloads taking query, queryResponse, messageId, conversationId, and isResponseReady are removed:

KoahCard(
    query = question,
    queryResponse = answer,
    messageId = messageId,
    isResponseReady = true,
)

The core composables have no isResponseReady gate in 1.0 — render the composable when your content is ready. To fetch before the answer finishes streaming, omit answer (it is optional on KoahAdContext.Conversation).

Sizing: from max-bounds overloads to KoahAxisSize

The deprecated overloads taking modifier, overrideMaxWidth, and overrideMaxHeight are removed. Express each bound as a KoahAxisSize, and move Modifier.padding(…) to the dedicated padding parameter:

KoahCard(
    adContext = KoahAdContext.Conversation(question = q, answer = a),
    modifier = Modifier.padding(16.dp),
    overrideMaxWidth = 400,
    overrideMaxHeight = 300,
    cacheKey = messageId,
)

There is no raw modifier parameter in 1.0. Sizing is owned by width / height and outer margin by padding — for anything else (weight, alignment, semantics), wrap the ad in your own Box. See Sizing for the full KoahAxisSize model (fixed, range, fill, or null for unbounded).

Rename messageId to cacheKey

The overloads that render a prefetched or sample ad take cacheKey instead of messageId, matching prefetchAd(cacheKey = …). Only the parameter name changes — the value and behavior are identical:

KoahCard(messageId = item.id)

KoahCard(sample = sampleAd, messageId = item.id)

This rename only breaks call sites that pass the argument by name (messageId = …). Positional call sites compile unchanged.

Install 1.0

Pin the stable version in your build.gradle.kts:

dependencies {
    implementation("com.koahlabs:koah-android:1.0.0")
}

Need help upgrading? Email support@koahlabs.com.

Was this helpful?