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

# How it works

> The session-to-render flow that powers every Kontext integration.

Kontext serves contextually relevant ads inside text-based AI apps — chat, search, and any interface where users talk to a model. Your app feeds the SDK the messages of a conversation as they happen; the SDK contacts our ad server in the background and renders the winning ad in the slot you mount in your UI.

## The flow

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Your app
    participant SDK as Kontext SDK
    participant Server as Kontext ad server

    App->>SDK: createSession(publisherToken, userId, conversationId)
    SDK->>Server: POST /init
    Server-->>SDK: enabled, preloadTimeout, ...

    Note over App,SDK: User sends a message
    App->>SDK: session.addMessage(message)
    SDK->>Server: POST /preload (debounced)
    Server-->>SDK: ads[] for the preload
    SDK-->>App: filled / no-fill event per messageId

    Note over App,SDK: Assistant replies
    App->>SDK: mount <InlineAd messageId="..." />
    SDK->>App: render ad in iframe

    SDK-->>App: viewed / clicked / error events
```

1. **Create a session.** Your app instantiates one `Session` per chat conversation, supplying your `publisherToken`, a stable `userId`, and a `conversationId`. The SDK calls `/init` in the background to fetch server-controlled flags (whether the session is enabled, the preload timeout, telemetry toggles).
2. **Feed messages to the SDK.** As the user and the assistant exchange messages, the app calls `session.addMessage(...)` for each one. This is the only signal the SDK needs to do its work.
3. **The SDK preloads ads in the background.** Each `addMessage` triggers a debounced `POST /preload` carrying the conversation context. The server returns one or more ads for the preload. The SDK pairs each ad to the latest assistant message id (see [Displaying ads](/concepts/displaying-ads) for the pairing rules) and emits a `filled` event for each id that got an ad, or `no-fill` otherwise.
4. **Mount an ad slot in your UI.** When the assistant's reply is on screen, your app renders `<InlineAd messageId="..." />` (the component name differs per SDK). The component is a renderer — it does not fetch — it simply looks up the cached ad for that `messageId` and renders the creative inside an iframe.
5. **Render-time events flow back to your app.** As the ad loads, becomes visible, or is clicked, the SDK emits `viewed`, `clicked`, and `error` events. Subscribe to them alongside `filled` / `no-fill` to drive your own UI — for example, to reveal an assistant bubble only once the ad has resolved.

## What you provide vs. what the SDK handles

| You provide                                                           | The SDK handles                                       |
| --------------------------------------------------------------------- | ----------------------------------------------------- |
| `publisherToken` (issued during onboarding)                           | `/init`, `/preload`, `/error`, `/debug` network calls |
| `userId`, `conversationId` (stable IDs you generate)                  | Ad cache, message-id matching, TTL                    |
| The list of messages, via `addMessage`                                | Debounce, retries, request cancellation               |
| The placement: where `<InlineAd />` is mounted                        | Iframe rendering, viewability tracking                |
| Optional regulatory signals (see [Compliance](/resources/compliance)) | TCF auto-collection from the standard CMP storage     |

## Where to next

<CardGroup cols={2}>
  <Card title="Pick your SDK" icon="rocket" href="/overview">
    Install an SDK, initialize a session, mount one component, see an ad — every SDK page is its own quickstart.
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/session">
    The mental model behind every Kontext integration: sessions, IDs, messages, events, and more.
  </Card>

  <Card title="Best practices" icon="list-check" href="/guides/best-practices">
    Pre-launch checklist — what to set up, what to monitor, how to get the highest fill rate.
  </Card>

  <Card title="Demos" icon="github" href="/resources/demos">
    Runnable example apps for every SDK — clone, drop in your publisher token, and run.
  </Card>
</CardGroup>