Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kontext.so/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
publisherToken
String
required
Your unique publisher token.
​
userId
String
required
Stable identifier for the end user. Used for personalization, frequency capping, and rewarded ads.
​
conversationId
String
required
Unique ID of the current conversation / chat thread.
​
enabledPlacementCodes
[String]?
Placement codes to request ads for. Defaults to ["inlineAd"] when nil or empty.
​
character
Character?
AI character metadata for contextual targeting.
​
variantId
String?
Publisher-defined cohort identifier (e.g. for A/B testing).
​
regulatory
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.
​
userEmail
String?
End-user email for frequency-cap deduplication.
​
advertisingId
String?
IDFA you collected yourself. Takes priority over the SDK’s automatic collection. Use with requestTrackingAuthorization: false.
​
vendorId
String?
IDFV you collected yourself. Falls back to UIDevice.current.identifierForVendor when nil.
​
requestTrackingAuthorization
Bool
Whether the SDK should auto-request ATT authorization. Defaults to true.
​
onEvent
(AdEvent) -> Void
Callback invoked on every ad lifecycle event. Called on the main thread.

​
Session

​
addMessage(_:options:)
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.
​
createAd(_:options:)
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"))
​
updateOptions(_:)
method
Live-update preload-scoped fields. See Guides → Live-updating session options.
​
destroy()
method
Tear down the session: cancel preloads, destroy ads, release web views. Idempotent.
​
eventPublisher
AnyPublisher<AdEvent, Never>
Combine publisher delivering the same events as onEvent. Useful for SwiftUI / Combine pipelines.
​
messages
[Message]
Read-only snapshot of messages tracked by the session.
​
sessionId
UUID?
Server-assigned session ID. nil until the first successful preload.
​
disabled
Bool
true if the server has permanently disabled the session via the /init response (e.g. geo-restriction). Subsequent preloads are skipped.
​
destroyed
Bool
true after destroy() is called.

​
MutablePublisherOptions

Subset of SessionOptions accepted by session.updateOptions(_:). Every field is optional — non-nil overwrites, nil leaves unchanged.
​
variantId
String?
​
regulatory
Regulatory?
​
userEmail
String?
​
advertisingId
String?
​
vendorId
String?

​
Message

​
id
String
required
Unique message ID.
​
role
Message.Role
required
.user or .assistant.
​
content
String
required
Message text.
​
createdAt
Date
Defaults to Date().

​
AdOptions

​
code
String
Placement code. Defaults to "inlineAd".
​
theme
String?
UI theme hint forwarded to the ad iframe (e.g. "dark").

​
AddMessageOptions

​
trackOnly
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.

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

No ad was returned for the placement (server 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).

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

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

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

The user clicked the ad.

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

The first token of the ad content was received.

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

Ad content streaming finished.

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

The SDK encountered an error while serving an ad.

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

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

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

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