跳转到主要内容

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.

这是 5 分钟接入的完整流程。开始之前，请确认你已经完成 安装。

​
1. 创建会话

引入 createSession()，为某个用户的某次对话配置会话。返回的 Session 是后续一切操作的入口——喂消息、创建广告、监听事件。 
import { createSession } from '@kontextso/sdk-js'

const session = createSession({
  publisherToken: '<your-publisher-token>',
  userId: 'user-1234',
  conversationId: 'conv-5678',
  character: {
    id: 'character-1234',
    name: 'John Doe',
    avatarUrl: 'https://example.com/avatar.png',
    greeting: 'Hello, how can I help you today?',
  },
  onEvent: ({ name, code, payload }) => {
    // 处理事件
  },
})
如果你使用 CDN 全局版本： 
const { createSession } = window.KontextSdk
const session = createSession({ /* ... */ })
说明：
  • userId 应在用户的整个生命周期内、跨会话与设备保持不变——它驱动个性化、频次封顶以及奖励广告。
  • conversationId 应在每个聊天线程（一个聊天室、一个工单、应用中的一次对话）内唯一。

​
2. 向 SDK 喂消息

SDK 会根据新的聊天消息预加载广告。无论是用户消息还是助手消息，每出现一条就调用一次 addMessage()——两种角色都需要喂入，Kontext 才能完整理解对话上下文。 
// 用户消息
session.addMessage({
  id: 'msg-1',
  role: 'user',
  content: 'Hello, how are you?',
  createdAt: new Date(),
})

// 助手回复
session.addMessage({
  id: 'msg-2',
  role: 'assistant',
  content: 'I am good, thank you!',
  createdAt: new Date(),
})
说明：
  • id 必须每条消息唯一且稳定——后续创建广告时会用同一个 id 引用。

​
3. 挂载广告

要展示广告，先为目标助手消息创建一个 Ad 实例，再将它挂载到一个 DOM 元素中。SDK 负责管理 iframe 及其生命周期。 
<div id="ad-msg-2"></div>

<script type="module">
  // ... 上一节中的 session 与消息

  const ad = session.createAd('msg-2') // 助手消息的 messageId
  ad.mount(document.getElementById('ad-msg-2'))
</script>
在典型的聊天 UI 中，你会这样做：
  1. 渲染消息列表。
  2. 为每条助手消息渲染一个占位的 <div> 作为广告容器。
  3. 当占位 DOM 存在后调用 session.createAd(messageId)，再调用 ad.mount(element)。
  4. 当消息被滚动出视野或对话结束时，调用 ad.destroy() 释放 iframe。
const ad = session.createAd('msg-2', { theme: 'dark' })
ad.mount(document.getElementById('ad-msg-2'))
// 之后，当消息被移除时：
ad.destroy()
如果你想一次完成，session.render({ messageId, element, theme }) 是 createAd + mount 的便捷封装。

​
4. 释放资源

对话结束或页面卸载时调用 session.destroy()。该方法是幂等的，且是取消进行中预加载、释放 iframe 资源的必要操作。 
session.destroy()

​
订阅事件

通过 onEvent 回调订阅每个广告的生命周期。每个事件都有稳定的字符串 name 和类型化的 payload： 
const session = createSession({
  // ...
  onEvent: (event) => {
    switch (event.name) {
      case 'ad.filled':
        console.log('filled:', event.payload.id, 'revenue=', event.payload.revenue)
        break
      case 'ad.clicked':
        console.log('clicked:', event.payload.url)
        break
      case 'ad.no-fill':
        console.log('no fill, skipCode=', event.payload.skipCode)
        break
    }
  },
})
每个与广告位相关的事件（ad.filled、ad.viewed、ad.clicked、ad.render-*、video.*、reward.granted）的顶层还携带一个 code 字段，标识匹配到的广告位——配置了多个 enabledPlacementCodes 的发布方可以据此区分。会话级事件（ad.no-fill、ad.error）则不带这个字段。 接入期间若需查看 SDK 内部诊断信息，可以再传入 onDebugEvent 回调——它会对 SDK 的每一个内部步骤回调 (name, data?)。