> ## 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 插件、喂入消息、挂载 <InlineAd>，并订阅事件。

这是 5 分钟接入的完整流程。开始之前，请确认你已经完成 [安装](/sdk/vue/installation)。

## 1. 安装插件

`KontextAdsPlugin` 会初始化一个会话，应用内的任意组件都可以通过 `useAds()` composable 访问到它。

```ts theme={null}
// main.ts
import { createApp } from 'vue'
import { KontextAdsPlugin } from '@kontextso/sdk-vue'
import App from './App.vue'

const app = createApp(App)

app.use(KontextAdsPlugin, {
  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 }) => {
    // 处理事件
  },
})

app.mount('#app')
```

如果你想把会话限定在组件树的某一部分，可以改用 `<AdsProvider>`——它接受与插件相同的选项。

```vue theme={null}
<script setup lang="ts">
import { AdsProvider } from '@kontextso/sdk-vue'

const character = {
  id: 'character-1234',
  name: 'John Doe',
  avatarUrl: 'https://example.com/avatar.png',
  greeting: 'Hello, how can I help you today?',
}
</script>

<template>
  <AdsProvider
    publisher-token="<your-publisher-token>"
    user-id="user-1234"
    conversation-id="conv-5678"
    :character="character"
  >
    <TheRestOfYourApplication />
  </AdsProvider>
</template>
```

## 2. 向 SDK 喂消息

SDK 会根据新的聊天消息预加载广告。无论是用户消息还是助手消息，每出现一条就用 `useAds()` 返回的 `addMessage()` 通知 SDK。

```vue theme={null}
<script setup lang="ts">
import { useAds } from '@kontextso/sdk-vue'

const { addMessage } = useAds()

// 对话中每条用户消息和助手消息都调用一次。
addMessage({
  id: '<unique-message-id>',
  role: '<user | assistant>',
  content: '<content of the message>',
  createdAt: new Date(),
})
</script>
```

## 3. 挂载 `<InlineAd>`

广告位（ad slot）是 UI 中专门用来渲染广告的区域，通常出现在助手消息下方。

把 `<InlineAd />` 放在希望广告出现的位置，并传入对应助手消息的 `messageId`。

```vue theme={null}
<script setup lang="ts">
import { InlineAd } from '@kontextso/sdk-vue'

defineProps<{ messages: Message[] }>()
</script>

<template>
  <div>
    <div v-for="m in messages" :key="m.id">
      <Message :message="m" />
      <InlineAd v-if="m.role === 'assistant'" :messageId="m.id" />
    </div>
  </div>
</template>
```

## 订阅事件

通过插件或 `<AdsProvider>` 的 `onEvent` prop 订阅广告生命周期事件。每个事件都有稳定的 `name` 和类型化的 `payload`：

```ts theme={null}
app.use(KontextAdsPlugin, {
  // ...
  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?)`。