Skip to main content
This is the 5-minute integration walkthrough. Before you start, make sure you’ve completed Installation.

​
1. Install the plugin

The KontextAdsPlugin initializes a session that’s available to every component in your app via the useAds() composable. 
// 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 }) => {
    // process events
  },
})

app.mount('#app')
If you’d rather scope a session to part of your component tree, use <AdsProvider> instead — it accepts the same options as the plugin. 
<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. Feed messages to the SDK

The SDK preloads ads in response to new chat messages. Call addMessage() from the useAds() composable whenever a user or assistant message is created. 
<script setup lang="ts">
import { useAds } from '@kontextso/sdk-vue'

const { addMessage } = useAds()

// Call this on every user and assistant message in the conversation.
addMessage({
  id: '<unique-message-id>',
  role: '<user | assistant>',
  content: '<content of the message>',
  createdAt: new Date(),
})
</script>

​
3. Mount <InlineAd>

An ad slot is a designated area in your UI where an ad can be rendered. In most cases, it appears below an assistant message. Place <InlineAd /> wherever the ad should appear and pass the messageId of the assistant message it’s associated with. 
<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>

​
Observing events

Subscribe to ad lifecycle events via the plugin or <AdsProvider> onEvent prop. Every event has a stable name and a typed payload: 
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
    }
  },
})
Every placement-attributed event (ad.filled, ad.viewed, ad.clicked, ad.render-*, video.*, reward.granted) also carries a top-level code field naming the matched placement, so publishers with multiple enabledPlacementCodes can disambiguate. Session-wide events (ad.no-fill, ad.error) omit it. For SDK-internal diagnostics during integration, also pass an onDebugEvent callback — it receives (name, data?) for every internal step.