> ## 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 参考
> Kotlin SDK 暴露的全部类型与方法。
## `KontextAds.createSession(...)`
```kotlin theme={null}
public fun createSession(context: Context, options: SessionOptions): Session
```
按给定的 `SessionOptions` 创建并返回一个新的 `Session`，并在后台触发 `/init`。请传入 `context.applicationContext`，避免 session 与单个 Activity 绑定。
## `SessionOptions`
你的发布方 token。
终端用户的稳定标识，用于个性化、频次控制与激励视频。
当前对话 / 会话的唯一 ID。
请求广告的 placement code 列表。为 null 或空列表时默认 `["inlineAd"]`。
广告服务器基础 URL 的覆盖。保持 null 即使用 Kontext 的生产环境。
用于内容定向的 AI 角色信息。
`java.net.URI` 类型——请用 `URI.create("…")` 构造，不能直接传 `String`。
发布方自定义的用户分组标识（用于 A/B 测试等）。
隐私 / 同意信号。如果你接入了符合 TCF 的 CMP，SDK 会自动收集 TCF（`gdpr` / `gdprConsent`）——仅在需要传 COPPA、GPP 或 US Privacy 时手动设置。
0、1 或 null。
IAB TCF v2 同意串。
0、1 或 null。
Global Privacy Platform 串。
当前请求适用的 GPP section ID 列表。
CCPA / LSPA 信号串。
用于跨设备频次去重的终端用户邮箱。
你自行采集的 GAID。优先级高于 SDK 的自动收集。
每次广告生命周期事件的回调。会在主线程上调用。
可选的诊断事件流——内部所有 SDK 事件（preload 开始/结束、iframe 生命周期、几何更新等）都会触发。集成期间很有用，生产环境可保持为 null。
## `Session`
追加一条 `Message` 到对话中。同步返回（不是 `suspend`）。用户消息会触发防抖后的预加载；助手消息让 SDK 把匹配到的广告绑定到广告位上。
```kotlin theme={null}
session.addMessage(Message(id = "m1", role = Role.USER, content = "Hi"))
session.addMessage(
Message(id = "m2", role = Role.USER, content = "Hi again"),
AddMessageOptions(trackOnly = true),
)
```
当 `trackOnly = true` 时，预加载会照常发送（用于上报分析数据），但不会生成广告。
返回指定 `messageId` 对应的 `Ad`。幂等——同一个 `messageId` + `code` + `theme` 的多次调用会返回同一个 `Ad`。请缓存返回值。
```kotlin theme={null}
val ad = session.createAd("m2")
val sidebar = session.createAd("m2", AdOptions(code = "sidebar", theme = "dark"))
```
动态更新会话级别的可变字段。见 [实践指南 → 动态更新会话选项](/sdk/kotlin/guides#动态更新会话选项)。
释放会话：取消预加载、销毁广告、释放 WebView 资源。幂等。`close()` 是它的别名（实现 `AutoCloseable`）。
与 `onEvent` 同源的事件 Flow。适合在 ViewModel 与协程管道中订阅。
当前会话追踪到的消息只读快照。
服务端分配的 session ID。在首次预加载成功之前为 `null`。
当服务端通过 `/init` 永久禁用会话（例如地域限制）时为 `true`。后续预加载会被跳过。
`destroy()` 被调用后为 `true`。
## `MutablePublisherOptions`
`session.updateOptions(...)` 接受的 `SessionOptions` 子集。所有字段均为可选——非 null 会覆盖原值，null 表示保持不变。
## `Message`
消息的唯一 ID。
`Role.USER` 或 `Role.ASSISTANT`。
消息文本。
默认 `Date()`。
## `AdOptions`
广告位 code。默认 `"inlineAd"`。
透传到 iframe 的主题提示（例如 `"dark"`）。
## `AddMessageOptions`
为 `true` 时，预加载仍会发送（用于上报分析数据），但不会为这条消息生成广告。默认 `false`。
## UI
### `InlineAd`（Compose，推荐）
```kotlin theme={null}
@Composable
public fun InlineAd(
messageId: String,
session: Session,
code: String? = null,
theme: String? = null,
modifier: Modifier = Modifier,
)
```
为指定 `messageId` 挂载广告。内部会调用 `session.createAd(...)`，挂载一个池化的 `WebView`，并把容器几何信息上报给 iframe。可以安全地放在 `LazyColumn` 中——底层 `Ad` 和 `WebView` 会在重组与滚动复用中保持存活。
另一个重载直接接收已经解析好的 `Ad`：
```kotlin theme={null}
@Composable
public fun InlineAd(ad: Ad, modifier: Modifier = Modifier)
```
### `InlineAdView`（View 互操作）
```kotlin theme={null}
public class InlineAdView(context: Context) : FrameLayout {
public var onHeightChange: ((Float) -> Unit)?
public fun bind(messageId: String, session: Session, code: String? = null, theme: String? = null)
}
```
适用于没有使用 Compose 的项目。inflate / 实例化后调用一次 `bind(messageId, session)`；订阅 `onHeightChange` 来撑开外层容器（例如 `RecyclerView` 行）。
## `AdEvent`
`AdEvent` 是 sealed class，每个 case 携带一个强类型的 payload。可以通过 `event.name` 拿到稳定的字符串标识。
### `AdEvent.Filled` — wire name `ad.filled`
返回了一个广告并绑定到了广告位。
该广告被匹配到的 placement code。当发布方配置了多个 `enabledPlacementCodes` 时用于区分。
### `AdEvent.NoFill` — wire name `ad.no-fill`
广告位没有返回广告（服务端 skip）。
跳过的原因码。
### `AdEvent.AdHeight` — wire name `ad.height`
iframe 上报了新的高度。用于撑开 `RecyclerView` 行的高度。`InlineAd` composable 会自动处理这件事。
### `AdEvent.Viewed` — wire name `ad.viewed`
广告被用户看到（符合 IAB MRC 可视性标准）。
### `AdEvent.Clicked` — wire name `ad.clicked`
用户点击了广告。
被点击的广告区域。
### `AdEvent.RenderStarted` — wire name `ad.render-started`
收到广告内容的第一个 token。
### `AdEvent.RenderCompleted` — wire name `ad.render-completed`
广告内容流式输出完毕。
### `AdEvent.Error` — wire name `ad.error`
SDK 在服务广告过程中遇到错误。
### `AdEvent.VideoStarted` — wire name `video.started`
### `AdEvent.VideoCompleted` — wire name `video.completed`
### `AdEvent.RewardGranted` — wire name `reward.granted`
激励视频流程中，用户达到发奖条件时触发。