API 参考

`KontextAds.createSession(...)`

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

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

`SessionOptions`

publisherToken

String

必填

你的发布方 token。

userId

String

必填

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

conversationId

String

必填

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

enabledPlacementCodes

List<String>?

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

adServerUrl

String?

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

character

Character?

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

显示属性

String

必填

name

String

必填

avatarUrl

String

必填

greeting

String?

persona

String?

`Session`

addMessage(message, options)

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

createAd(messageId, options)

method

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

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

updateOptions(partial)

method

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

destroy()

method

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

events

SharedFlow<AdEvent>

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

messages

List<Message>

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

sessionId

UUID?

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

disabled

Boolean

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

destroyed

Boolean

destroy() 被调用后为 true。

`MutablePublisherOptions`

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

variantId

String?

regulatory

Regulatory?

userEmail

String?

advertisingId

String?

`Message`

String

必填

消息的唯一 ID。

role

Role

必填

Role.USER 或 Role.ASSISTANT。

content

String

必填

消息文本。

createdAt

Date

默认 Date()。

`AdOptions`

code

String

广告位 code。默认 "inlineAd"。

theme

String?

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

`AddMessageOptions`

trackOnly

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

bidId

UUID

code

String

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

revenue

Double?

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

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

显示 NoFill

skipCode

String

跳过的原因码。

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

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

显示 AdHeight

bidId

UUID

messageId

String

height

Float

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

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

显示 Viewed

bidId

UUID

content

String

messageId

String

format

String

revenue

Double?

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

用户点击了广告。

显示 Clicked

bidId

UUID

content

String

messageId

String

url

String

format

String

area

String

被点击的广告区域。

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

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

显示 RenderStarted

bidId

UUID

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

广告内容流式输出完毕。

显示 RenderCompleted

bidId

UUID

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

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

显示 Error

message

String

errCode

String

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

显示 VideoStarted

bidId

UUID

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

显示 VideoCompleted

bidId

UUID

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

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

显示 RewardGranted

bidId

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`

入门

核心概念

实践指南

SDK

资源

Documentation Index

​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`