API reference

`KontextAds.createSession(_:)`

@MainActor
public static func createSession(_ options: SessionOptions) -> Session

Returns a new Session configured from the given SessionOptions. Fires /init in the background.

`SessionOptions`

String

required

Your unique publisher token.

String

required

Stable identifier for the end user. Used for personalization, frequency capping, and rewarded ads.

String

required

Unique ID of the current conversation / chat thread.

[String]?

Placement codes to request ads for. Defaults to ["inlineAd"] when nil or empty.

Character?

AI character metadata for contextual targeting.

Show Properties

String

required

String

required

URL

required

String?

[String]?

Bool?

String?

Publisher-defined cohort identifier (e.g. for A/B testing).

Regulatory?

Privacy / consent signals. TCF (gdpr / gdprConsent) is collected automatically if a TCF-compliant CMP is integrated — set manually only for COPPA, GPP, or US Privacy.

Show Properties

0, 1, or nil.

IAB TCF v2 consent string.

Int?

0, 1, or nil.

String?

Global Privacy Platform string.

[Int]?

GPP section IDs that apply.

String?

CCPA / LSPA string.

String?

End-user email for frequency-cap deduplication.

String?

IDFA you collected yourself. Takes priority over the SDK’s automatic collection. Use with requestTrackingAuthorization: false.

String?

IDFV you collected yourself. Falls back to UIDevice.current.identifierForVendor when nil.

Bool

Whether the SDK should auto-request ATT authorization. Defaults to true.

(AdEvent) -> Void

Callback invoked on every ad lifecycle event. Called on the main thread.

`Session`

method

Append a Message to the conversation. Synchronous. User messages trigger a debounced preload.

session.addMessage(Message(id: "m1", role: .user, content: "Hi"))
session.addMessage(
    Message(id: "m2", role: .user, content: "Hi"),
    options: AddMessageOptions(trackOnly: true)
)

When trackOnly: true, the preload is sent for analytics but no ad is generated.

method

Returns an Ad for the given messageId. Idempotent — repeated calls with the same messageId + placement code return the same Ad. Cache the result.

let ad = session.createAd("m2")
let sidebar = session.createAd("m2", options: AdOptions(code: "sidebar", theme: "dark"))

method

Live-update preload-scoped fields. See Guides → Live-updating session options.

method

Tear down the session: cancel preloads, destroy ads, release web views. Idempotent.

AnyPublisher<AdEvent, Never>

Combine publisher delivering the same events as onEvent. Useful for SwiftUI / Combine pipelines.

[Message]

Read-only snapshot of messages tracked by the session.

UUID?

Server-assigned session ID. nil until the first successful preload.

Bool

true if the server has permanently disabled the session via the /init response (e.g. geo-restriction). Subsequent preloads are skipped.

Bool

true after destroy() is called.

`MutablePublisherOptions`

Subset of SessionOptions accepted by session.updateOptions(_:). Every field is optional — non-nil overwrites, nil leaves unchanged.

String?

Regulatory?

String?

`Message`

String

required

Unique message ID.

Message.Role

required

.user or .assistant.

String

required

Message text.

Date

Defaults to Date().

`AdOptions`

String

Placement code. Defaults to "inlineAd".

String?

UI theme hint forwarded to the ad iframe (e.g. "dark").

`AddMessageOptions`

Bool

When true, the preload is still sent (for analytics) but no ad is generated for this message. Defaults to false.

`AdEvent`

AdEvent is an enum with one typed payload per case. Every case has a stable string identifier accessible via event.name.

`.filled(FilledData)` — wire name `ad.filled`

An ad was returned and linked to the placement.

Show FilledData

UUID

String

Placement code this ad was matched to. Required for publishers with multiple enabledPlacementCodes.

Double?

`.noFill(NoFillData)` — wire name `ad.no-fill`

No ad was returned for the placement (server skipped).

Show NoFillData

String

Reason the ad was skipped.

`.adHeight(AdHeightData)` — wire name `ad.height`

The ad iframe reported a new height. Use to size the surrounding container (especially in UIKit UITableView / UICollectionView cells).

Show AdHeightData

UUID

String

CGFloat

`.viewed(ViewedData)` — wire name `ad.viewed`

The ad was viewed by the user (IAB MRC viewability standard).

Show ViewedData

UUID

String

Double?

`.clicked(ClickedData)` — wire name `ad.clicked`

The user clicked the ad.

Show ClickedData

UUID

String

Region of the ad that was clicked.

`.renderStarted(RenderStartedData)` — wire name `ad.render-started`

The first token of the ad content was received.

Show RenderStartedData

UUID

`.renderCompleted(RenderCompletedData)` — wire name `ad.render-completed`

Ad content streaming finished.

Show RenderCompletedData

UUID

`.error(ErrorData)` — wire name `ad.error`

The SDK encountered an error while serving an ad.

Show ErrorData

String

`.videoStarted(VideoStartedData)` — wire name `video.started`

Show VideoStartedData

UUID

`.videoCompleted(VideoCompletedData)` — wire name `video.completed`

Show VideoCompletedData

UUID

`.rewardGranted(RewardGrantedData)` — wire name `reward.granted`

Fired for rewarded-ad flows after the user qualifies for a reward.

Show RewardGrantedData

UUID

Get Started

Concepts

Guides

SDKs

Resources

`KontextAds.createSession(_:)`

`SessionOptions`

`Session`

`MutablePublisherOptions`

`Message`

`AdOptions`

`AddMessageOptions`

`AdEvent`

`.filled(FilledData)` — wire name `ad.filled`

`.noFill(NoFillData)` — wire name `ad.no-fill`

`.adHeight(AdHeightData)` — wire name `ad.height`

`.viewed(ViewedData)` — wire name `ad.viewed`

`.clicked(ClickedData)` — wire name `ad.clicked`

`.renderStarted(RenderStartedData)` — wire name `ad.render-started`

`.renderCompleted(RenderCompletedData)` — wire name `ad.render-completed`

`.error(ErrorData)` — wire name `ad.error`

`.videoStarted(VideoStartedData)` — wire name `video.started`

`.videoCompleted(VideoCompletedData)` — wire name `video.completed`

`.rewardGranted(RewardGrantedData)` — wire name `reward.granted`

​KontextAds.createSession(_:)

​SessionOptions

​Session

​MutablePublisherOptions

​Message

​AdOptions

​AddMessageOptions

​AdEvent

​.filled(FilledData) — wire name ad.filled

​.noFill(NoFillData) — wire name ad.no-fill

​.adHeight(AdHeightData) — wire name ad.height

​.viewed(ViewedData) — wire name ad.viewed

​.clicked(ClickedData) — wire name ad.clicked

​.renderStarted(RenderStartedData) — wire name ad.render-started

​.renderCompleted(RenderCompletedData) — wire name ad.render-completed

​.error(ErrorData) — wire name ad.error

​.videoStarted(VideoStartedData) — wire name video.started

​.videoCompleted(VideoCompletedData) — wire name video.completed

​.rewardGranted(RewardGrantedData) — wire name reward.granted

`KontextAds.createSession(_:)`

`SessionOptions`

`Session`

`MutablePublisherOptions`

`Message`

`AdOptions`

`AddMessageOptions`

`AdEvent`

`.filled(FilledData)` — wire name `ad.filled`

`.noFill(NoFillData)` — wire name `ad.no-fill`

`.adHeight(AdHeightData)` — wire name `ad.height`

`.viewed(ViewedData)` — wire name `ad.viewed`

`.clicked(ClickedData)` — wire name `ad.clicked`

`.renderStarted(RenderStartedData)` — wire name `ad.render-started`

`.renderCompleted(RenderCompletedData)` — wire name `ad.render-completed`

`.error(ErrorData)` — wire name `ad.error`

`.videoStarted(VideoStartedData)` — wire name `video.started`

`.videoCompleted(VideoCompletedData)` — wire name `video.completed`

`.rewardGranted(RewardGrantedData)` — wire name `reward.granted`