SDKsiOS

Migrate to 1.0

Replace the legacy prefetch / resolveAd / cancelPrefetch calls, KoahAdLoader, and the override-sizing initializers with the 1.0 API.

1.0 is a hard break with no compatibility shims — the 0.x symbols below no longer exist in the package. Apps staying on a 0.x release keep working; upgrading the package to 1.0 requires these code changes. 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 iOS SDK (the KoahAds Swift package) on a 0.x version. Migrate my integration to the 1.0 API. Read https://docs.koahlabs.com/sdk/ios/migration and apply it to this project.

What changes

Aspect	0.x	1.0
Prefetch	`Koah.shared.prefetch(query:queryResponse:messageId:conversationId:)`	`Koah.shared.prefetchAd(adContext:cacheKey:)`
Await a result	`Koah.shared.resolveAd(query:queryResponse:messageId:conversationId:)` returns `KoahAdState`	`Koah.shared.requestAd(adContext:cacheKey:)` returns `KoahAdResult`
Cancel	`Koah.shared.cancelPrefetch(messageId:)`	`Koah.shared.cancelPrefetchAd(cacheKey:)`
Observable loading state	`KoahAdLoader` with a published `state`	Removed — warm with `prefetchAd`, render with `KoahCard(cacheKey:)`
Card size bounds	`KoahCard(adContext:overrideMaxWidth:overrideMaxHeight:cacheKey:)`	`width:` / `height:` of type `KoahAxisSize`: `.fixed(_:)`, `.range(min:max:)`, `.fill`

messageId is the same value 1.0 calls cacheKey — keep passing your stable per-slot id. conversationId moves inside the context as externalConversationId.

Migrate each call

Prefetch

Koah.shared.prefetch(
    query: question,
    queryResponse: answer,
    messageId: messageId
)

The legacy calls were conversation-only; KoahAdContext also has .article(...), .feed(...), and .static for other surfaces — see Ad context.

Resolve a result

let state = await Koah.shared.resolveAd(
    query: question,
    queryResponse: answer,
    messageId: messageId
)
if state == .filled { showAdSlot() }

The APIs that returned KoahAdState are gone — results now arrive as KoahAdResult: .filled(fromCache:), .noFill(fromCache:), or .error(message:fromCache:).

Cancel a prefetch

Koah.shared.cancelPrefetch(messageId: messageId)

Replace KoahAdLoader

struct MessageRow: View {
    let msg: Message
    @StateObject private var adLoader: KoahAdLoader

    init(msg: Message) {
        self.msg = msg
        _adLoader = StateObject(wrappedValue: KoahAdLoader(
            query: msg.query, queryResponse: msg.text, messageId: msg.id
        ))
    }

    var body: some View {
        if adLoader.state == .filled {
            KoahCard(cacheKey: msg.id)
        }
    }
}

prefetchAd warms the cache (concurrent calls for the same cacheKey share one in-flight fetch) and KoahCard(cacheKey:) renders the warmed slot — nothing renders on no-fill. To drive your own reserve/collapse layout from the outcome, use requestAd instead — see Use Cases.

Replace size overrides

KoahCard(
    adContext: .conversation(question: question, answer: answer),
    overrideMaxWidth: 360,
    overrideMaxHeight: 420,
    cacheKey: messageId
)

.range(max:) reproduces the old max-only bound exactly. The full KoahAxisSize model — .fixed(_:), .range(min:max:), .fill, or nil to leave an axis unbounded — is in Card sizing.

1.0 also changes when impressions are billed — an impression now requires the ad to actually be on screen, so counts step down where ads render off screen or clipped. No code changes; see the changelog.

Install 1.0

Update your Swift Package dependency to the stable 1.0 release. An up-to-next-major range starting at 0.x will not upgrade across the 1.0 boundary:

dependencies: [
  .package(url: "https://github.com/koahlabs/swift-package-manager-koah-ads", from: "1.1.0")
]

In Xcode: File → Add Package Dependencies…, then Dependency Rule → Up to Next Major Version, starting at 1.1.0.

Need help upgrading? Email support@koahlabs.com.