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

# 工作原理

> 贯穿每一次 Kontext 接入的核心流程：从创建会话到渲染广告。

Kontext 在基于文本的 AI 应用——聊天、搜索，以及任何用户与模型对话的界面中——投放上下文相关的广告。你的应用在对话发生时把消息喂给 SDK；SDK 在后台调用我们的广告服务，并将中标广告渲染到你 UI 中挂载的广告位中。

## 流程

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as 你的应用
    participant SDK as Kontext SDK
    participant Server as Kontext 广告服务

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

    Note over App,SDK: 用户发送消息
    App->>SDK: session.addMessage(message)
    SDK->>Server: POST /preload (debounced)
    Server-->>SDK: ads[]（本次预加载返回的广告）
    SDK-->>App: 按 messageId 触发 filled / no-fill 事件

    Note over App,SDK: 助手回复
    App->>SDK: 挂载 <InlineAd messageId="..." />
    SDK->>App: 在 iframe 中渲染广告

    SDK-->>App: viewed / clicked / error 事件
```

1. **创建会话。** 你的应用为每个聊天会话创建一个 `Session` 实例，传入你的 `publisherToken`、一个稳定的 `userId` 和 `conversationId`。SDK 会在后台调用 `/init` 拉取服务端控制的开关（会话是否启用、preload 超时、遥测开关等）。
2. **向 SDK 喂消息。** 用户和助手每交换一条消息，应用就调用一次 `session.addMessage(...)`。这是 SDK 完成所有工作所需的唯一信号。
3. **SDK 在后台预加载广告。** 每次 `addMessage` 都会触发一次防抖后的 `POST /preload`，携带对话上下文。服务端会针对本次预加载返回一个或多个广告。SDK 会把每个广告绑定到最新一条助手消息的 id（具体配对规则见 [展示广告](/concepts/displaying-ads)），并为每个拿到广告的 id 触发 `filled` 事件，否则触发 `no-fill`。
4. **在 UI 中挂载广告位。** 当助手的回复出现在屏幕上时，应用渲染 `<InlineAd messageId="..." />`（具体组件名因 SDK 而异）。该组件只是一个渲染器——它不会发起请求——只是根据 `messageId` 查找已缓存的广告并把素材渲染进 iframe。
5. **渲染期事件流回你的应用。** 当广告加载、可见或被点击时，SDK 会触发 `viewed`、`clicked` 和 `error` 事件。结合 `filled` / `no-fill` 一起订阅，可以驱动你自己的 UI——例如等广告就绪后再显示助手气泡。

## 你提供什么 vs SDK 处理什么

| 你提供                                    | SDK 处理                                     |
| -------------------------------------- | ------------------------------------------ |
| `publisherToken`（onboarding 时发放）       | `/init`、`/preload`、`/error`、`/debug` 等网络请求 |
| `userId`、`conversationId`（你生成的稳定 ID）   | 广告缓存、按 message id 匹配、TTL                   |
| 通过 `addMessage` 传入消息列表                 | 防抖、重试、请求取消                                 |
| 决定 `<InlineAd />` 挂载在哪里                | iframe 渲染、可见性（viewability）追踪               |
| 可选的合规信号（见 [合规](/resources/compliance)） | 自动从标准 CMP 存储位置读取 TCF                       |

## 下一步

<CardGroup cols={2}>
  <Card title="选择你的 SDK" icon="rocket" href="/overview">
    安装 SDK、初始化会话、挂载一个组件并看到广告——每个 SDK 页面本身就是它的快速开始。
  </Card>

  <Card title="核心概念" icon="book" href="/concepts/session">
    每次 Kontext 接入背后的思维模型：会话、ID、消息、事件等。
  </Card>

  <Card title="最佳实践" icon="list-check" href="/guides/best-practices">
    上线前的自查清单——需要配置什么、需要监控什么、如何获得最高的填充率。
  </Card>

  <Card title="Demo" icon="github" href="/resources/demos">
    每个 SDK 都有可运行的示例应用——克隆下来填入你的 publisher token 即可运行。
  </Card>
</CardGroup>