> ## 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.

# API reference

> Every type and method exposed by the Swift SDK.

## `KontextAds.createSession(_:)`

```swift theme={null}
@MainActor
public static func createSession(_ options: SessionOptions) -> Session
```

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

## `SessionOptions`

<ParamField path="publisherToken" type="String" required>
  Your unique publisher token.
</ParamField>

<ParamField path="userId" type="String" required>
  Stable identifier for the end user. Used for personalization, frequency capping, and rewarded ads.
</ParamField>

<ParamField path="conversationId" type="String" required>
  Unique ID of the current conversation / chat thread.
</ParamField>

<ParamField path="enabledPlacementCodes" type="[String]?" optional>
  Placement codes to request ads for. Defaults to `["inlineAd"]` when nil or empty.
</ParamField>

<ParamField path="character" type="Character?" optional>
  AI character metadata for contextual targeting.

  <Expandable title="Properties">
    <ParamField path="id" type="String" required />

    <ParamField path="name" type="String" required />

    <ParamField path="avatarUrl" type="URL" required />

    <ParamField path="greeting" type="String?" optional />

    <ParamField path="persona" type="String?" optional />

    <ParamField path="tags" type="[String]?" optional />

    <ParamField path="isNsfw" type="Bool?" optional />
  </Expandable>
</ParamField>

<ParamField path="variantId" type="String?" optional>
  Publisher-defined cohort identifier (e.g. for A/B testing).
</ParamField>

<ParamField path="regulatory" type="Regulatory?" optional>
  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.

  <Expandable title="Properties">
    <ParamField path="gdpr" type="Int?" optional>0, 1, or nil.</ParamField>
    <ParamField path="gdprConsent" type="String?" optional>IAB TCF v2 consent string.</ParamField>
    <ParamField path="coppa" type="Int?" optional>0, 1, or nil.</ParamField>
    <ParamField path="gpp" type="String?" optional>Global Privacy Platform string.</ParamField>
    <ParamField path="gppSid" type="[Int]?" optional>GPP section IDs that apply.</ParamField>
    <ParamField path="usPrivacy" type="String?" optional>CCPA / LSPA string.</ParamField>
  </Expandable>
</ParamField>

<ParamField path="userEmail" type="String?" optional>
  End-user email for frequency-cap deduplication.
</ParamField>

<ParamField path="advertisingId" type="String?" optional>
  IDFA you collected yourself. Takes priority over the SDK's automatic collection. Use with `requestTrackingAuthorization: false`.
</ParamField>

<ParamField path="vendorId" type="String?" optional>
  IDFV you collected yourself. Falls back to `UIDevice.current.identifierForVendor` when nil.
</ParamField>

<ParamField path="requestTrackingAuthorization" type="Bool" optional>
  Whether the SDK should auto-request ATT authorization. Defaults to `true`.
</ParamField>

<ParamField path="onEvent" type="(AdEvent) -> Void" optional>
  Callback invoked on every ad lifecycle event. Called on the main thread.
</ParamField>

## `Session`

<ParamField path="addMessage(_:options:)" type="method">
  Append a `Message` to the conversation. Synchronous. User messages trigger a debounced preload.

  ```swift theme={null}
  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.
</ParamField>

<ParamField path="createAd(_:options:)" type="method">
  Returns an `Ad` for the given `messageId`. Idempotent — repeated calls with the same `messageId` + placement code return the same `Ad`. Cache the result.

  ```swift theme={null}
  let ad = session.createAd("m2")
  let sidebar = session.createAd("m2", options: AdOptions(code: "sidebar", theme: "dark"))
  ```
</ParamField>

<ParamField path="updateOptions(_:)" type="method">
  Live-update preload-scoped fields. See [Guides → Live-updating session options](/sdk/swift/guides#live-updating-session-options).
</ParamField>

<ParamField path="destroy()" type="method">
  Tear down the session: cancel preloads, destroy ads, release web views. Idempotent.
</ParamField>

<ParamField path="eventPublisher" type="AnyPublisher<AdEvent, Never>" property>
  Combine publisher delivering the same events as `onEvent`. Useful for SwiftUI / Combine pipelines.
</ParamField>

<ParamField path="messages" type="[Message]" property>
  Read-only snapshot of messages tracked by the session.
</ParamField>

<ParamField path="sessionId" type="UUID?" property>
  Server-assigned session ID. `nil` until the first successful preload.
</ParamField>

<ParamField path="disabled" type="Bool" property>
  `true` if the server has permanently disabled the session via the `/init` response (e.g. geo-restriction). Subsequent preloads are skipped.
</ParamField>

<ParamField path="destroyed" type="Bool" property>
  `true` after `destroy()` is called.
</ParamField>

## `MutablePublisherOptions`

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

<ParamField path="variantId" type="String?" optional />

<ParamField path="regulatory" type="Regulatory?" optional />

<ParamField path="userEmail" type="String?" optional />

<ParamField path="advertisingId" type="String?" optional />

<ParamField path="vendorId" type="String?" optional />

## `Message`

<ParamField path="id" type="String" required>Unique message ID.</ParamField>
<ParamField path="role" type="Message.Role" required>`.user` or `.assistant`.</ParamField>
<ParamField path="content" type="String" required>Message text.</ParamField>
<ParamField path="createdAt" type="Date" optional>Defaults to `Date()`.</ParamField>

## `AdOptions`

<ParamField path="code" type="String" optional>Placement code. Defaults to `"inlineAd"`.</ParamField>
<ParamField path="theme" type="String?" optional>UI theme hint forwarded to the ad iframe (e.g. `"dark"`).</ParamField>

## `AddMessageOptions`

<ParamField path="trackOnly" type="Bool" optional>
  When `true`, the preload is still sent (for analytics) but no ad is generated for this message. Defaults to `false`.
</ParamField>

## `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.

<Expandable title="FilledData">
  <ParamField path="bidId" type="UUID" />

  <ParamField path="code" type="String">Placement code this ad was matched to. Required for publishers with multiple `enabledPlacementCodes`.</ParamField>

  <ParamField path="revenue" type="Double?" />
</Expandable>

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

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

<Expandable title="NoFillData">
  <ParamField path="skipCode" type="String">Reason the ad was skipped.</ParamField>
</Expandable>

### `.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).

<Expandable title="AdHeightData">
  <ParamField path="bidId" type="UUID" />

  <ParamField path="messageId" type="String" />

  <ParamField path="height" type="CGFloat" />
</Expandable>

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

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

<Expandable title="ViewedData">
  <ParamField path="bidId" type="UUID" />

  <ParamField path="content" type="String" />

  <ParamField path="messageId" type="String" />

  <ParamField path="format" type="String" />

  <ParamField path="revenue" type="Double?" />
</Expandable>

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

The user clicked the ad.

<Expandable title="ClickedData">
  <ParamField path="bidId" type="UUID" />

  <ParamField path="content" type="String" />

  <ParamField path="messageId" type="String" />

  <ParamField path="url" type="String" />

  <ParamField path="format" type="String" />

  <ParamField path="area" type="String">Region of the ad that was clicked.</ParamField>
</Expandable>

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

The first token of the ad content was received.

<Expandable title="RenderStartedData">
  <ParamField path="bidId" type="UUID" />
</Expandable>

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

Ad content streaming finished.

<Expandable title="RenderCompletedData">
  <ParamField path="bidId" type="UUID" />
</Expandable>

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

The SDK encountered an error while serving an ad.

<Expandable title="ErrorData">
  <ParamField path="message" type="String" />

  <ParamField path="errCode" type="String" />
</Expandable>

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

<Expandable title="VideoStartedData">
  <ParamField path="bidId" type="UUID" />
</Expandable>

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

<Expandable title="VideoCompletedData">
  <ParamField path="bidId" type="UUID" />
</Expandable>

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

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

<Expandable title="RewardGrantedData">
  <ParamField path="bidId" type="UUID" />
</Expandable>