API 参考

`KontextAds.createSession(...)`

public fun createSession(context: Context, options: SessionOptions): Session

按给定的 SessionOptions 创建并返回一个新的 Session，并在后台触发 /init。请传入 context.applicationContext，避免 session 与单个 Activity 绑定。

`SessionOptions`

String

必填

你的发布方 token。

String

必填

终端用户的稳定标识，用于个性化、频次控制与激励视频。

String

必填

当前对话 / 会话的唯一 ID。

List<String>?

请求广告的 placement code 列表。为 null 或空列表时默认 ["inlineAd"]。

String?

广告服务器基础 URL 的覆盖。保持 null 即使用 Kontext 的生产环境。

Character?

用于内容定向的 AI 角色信息。

显示属性

String

必填

String

必填

URI

必填

java.net.URI 类型——请用 URI.create("…") 构造，不能直接传 String。

String?

List<String>?

Boolean?

String?

发布方自定义的用户分组标识（用于 A/B 测试等）。

Regulatory?

隐私 / 同意信号。如果你接入了符合 TCF 的 CMP，SDK 会自动收集 TCF（gdpr / gdprConsent）——仅在需要传 COPPA、GPP 或 US Privacy 时手动设置。

显示属性

0、1 或 null。

IAB TCF v2 同意串。

Int?

0、1 或 null。

String?

Global Privacy Platform 串。

List<Int>?

当前请求适用的 GPP section ID 列表。

String?

CCPA / LSPA 信号串。

String?

用于跨设备频次去重的终端用户邮箱。

String?

你自行采集的 GAID。优先级高于 SDK 的自动收集。

(AdEvent) -> Unit

每次广告生命周期事件的回调。会在主线程上调用。

(String, Any?) -> Unit

可选的诊断事件流——内部所有 SDK 事件（preload 开始/结束、iframe 生命周期、几何更新等）都会触发。集成期间很有用，生产环境可保持为 null。

`Session`

method

追加一条 Message 到对话中。同步返回（不是 suspend）。用户消息会触发防抖后的预加载；助手消息让 SDK 把匹配到的广告绑定到广告位上。

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 时，预加载会照常发送（用于上报分析数据），但不会生成广告。

method

返回指定 messageId 对应的 Ad。幂等——同一个 messageId + code + theme 的多次调用会返回同一个 Ad。请缓存返回值。

val ad = session.createAd("m2")
val sidebar = session.createAd("m2", AdOptions(code = "sidebar", theme = "dark"))

method

动态更新会话级别的可变字段。见实践指南 → 动态更新会话选项。

method

释放会话：取消预加载、销毁广告、释放 WebView 资源。幂等。close() 是它的别名（实现 AutoCloseable）。

SharedFlow<AdEvent>

与 onEvent 同源的事件 Flow。适合在 ViewModel 与协程管道中订阅。

List<Message>

当前会话追踪到的消息只读快照。

UUID?

服务端分配的 session ID。在首次预加载成功之前为 null。

Boolean

当服务端通过 /init 永久禁用会话（例如地域限制）时为 true。后续预加载会被跳过。

Boolean

destroy() 被调用后为 true。

`MutablePublisherOptions`

session.updateOptions(...) 接受的 SessionOptions 子集。所有字段均为可选——非 null 会覆盖原值，null 表示保持不变。

String?

Regulatory?

String?

`Message`

String

必填

消息的唯一 ID。

Role

必填

Role.USER 或 Role.ASSISTANT。

String

必填

消息文本。

Date

默认 Date()。

`AdOptions`

String

广告位 code。默认 "inlineAd"。

String?

透传到 iframe 的主题提示（例如 "dark"）。

`AddMessageOptions`

Boolean

为 true 时，预加载仍会发送（用于上报分析数据），但不会为这条消息生成广告。默认 false。

UI

`InlineAd`（Compose，推荐）

@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：

@Composable
public fun InlineAd(ad: Ad, modifier: Modifier = Modifier)

`InlineAdView`（View 互操作）

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`

返回了一个广告并绑定到了广告位。

显示 Filled

UUID

String

该广告被匹配到的 placement code。当发布方配置了多个 enabledPlacementCodes 时用于区分。

Double?

`AdEvent.NoFill` — wire name `ad.no-fill`

广告位没有返回广告（服务端 skip）。

显示 NoFill

String

跳过的原因码。

`AdEvent.AdHeight` — wire name `ad.height`

iframe 上报了新的高度。用于撑开 RecyclerView 行的高度。InlineAd composable 会自动处理这件事。

显示 AdHeight

UUID

String

Float

`AdEvent.Viewed` — wire name `ad.viewed`

广告被用户看到（符合 IAB MRC 可视性标准）。

显示 Viewed

UUID

String

Double?

`AdEvent.Clicked` — wire name `ad.clicked`

用户点击了广告。

显示 Clicked

UUID

String

被点击的广告区域。

`AdEvent.RenderStarted` — wire name `ad.render-started`

收到广告内容的第一个 token。

显示 RenderStarted

UUID

`AdEvent.RenderCompleted` — wire name `ad.render-completed`

广告内容流式输出完毕。

显示 RenderCompleted

UUID

`AdEvent.Error` — wire name `ad.error`

SDK 在服务广告过程中遇到错误。

显示 Error

String

`AdEvent.VideoStarted` — wire name `video.started`

显示 VideoStarted

UUID

`AdEvent.VideoCompleted` — wire name `video.completed`

显示 VideoCompleted

UUID

`AdEvent.RewardGranted` — wire name `reward.granted`

激励视频流程中，用户达到发奖条件时触发。

显示 RewardGranted

UUID

入门

核心概念

实践指南

SDK

资源

`KontextAds.createSession(...)`

`SessionOptions`

`Session`

`MutablePublisherOptions`

`Message`

`AdOptions`

`AddMessageOptions`

UI

`InlineAd`（Compose，推荐）

`InlineAdView`（View 互操作）

`AdEvent`

`AdEvent.Filled` — wire name `ad.filled`

`AdEvent.NoFill` — wire name `ad.no-fill`

`AdEvent.AdHeight` — wire name `ad.height`

`AdEvent.Viewed` — wire name `ad.viewed`

`AdEvent.Clicked` — wire name `ad.clicked`

`AdEvent.RenderStarted` — wire name `ad.render-started`

`AdEvent.RenderCompleted` — wire name `ad.render-completed`

`AdEvent.Error` — wire name `ad.error`

`AdEvent.VideoStarted` — wire name `video.started`

`AdEvent.VideoCompleted` — wire name `video.completed`

`AdEvent.RewardGranted` — wire name `reward.granted`

​KontextAds.createSession(...)

​SessionOptions

​Session

​MutablePublisherOptions

​Message

​AdOptions

​AddMessageOptions

​UI

​InlineAd（Compose，推荐）

​InlineAdView（View 互操作）

​AdEvent

​AdEvent.Filled — wire name ad.filled

​AdEvent.NoFill — wire name ad.no-fill

​AdEvent.AdHeight — wire name ad.height

​AdEvent.Viewed — wire name ad.viewed

​AdEvent.Clicked — wire name ad.clicked

​AdEvent.RenderStarted — wire name ad.render-started

​AdEvent.RenderCompleted — wire name ad.render-completed

​AdEvent.Error — wire name ad.error

​AdEvent.VideoStarted — wire name video.started

​AdEvent.VideoCompleted — wire name video.completed

​AdEvent.RewardGranted — wire name reward.granted

`KontextAds.createSession(...)`

`SessionOptions`

`Session`

`MutablePublisherOptions`

`Message`

`AdOptions`

`AddMessageOptions`

UI

`InlineAd`（Compose，推荐）

`InlineAdView`（View 互操作）

`AdEvent`

`AdEvent.Filled` — wire name `ad.filled`

`AdEvent.NoFill` — wire name `ad.no-fill`

`AdEvent.AdHeight` — wire name `ad.height`

`AdEvent.Viewed` — wire name `ad.viewed`

`AdEvent.Clicked` — wire name `ad.clicked`

`AdEvent.RenderStarted` — wire name `ad.render-started`

`AdEvent.RenderCompleted` — wire name `ad.render-completed`

`AdEvent.Error` — wire name `ad.error`

`AdEvent.VideoStarted` — wire name `video.started`

`AdEvent.VideoCompleted` — wire name `video.completed`

`AdEvent.RewardGranted` — wire name `reward.granted`