> ## 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.

# API reference

> Plugin options, composable, components, and events exposed by the Vue SDK.

## Plugin / `AdsProvider` options

<ParamField path="publisherToken" type="string" required>
  Your unique publisher token.
</ParamField>

<ParamField path="userId" type="string" required>
  Unique identifier that remains the same for the user's lifetime (used for retargeting and rewarded ads).
</ParamField>

<ParamField path="userEmail" type="string" optional>
  Email of the user.
</ParamField>

<ParamField path="conversationId" type="string" required>
  Unique ID of the conversation.
</ParamField>

<ParamField path="enabledPlacementCodes" type="array" optional>
  Placement codes enabled for the conversation. Defaults to `['inlineAd']`.
</ParamField>

<ParamField path="character" type="object" optional>
  Character object used in this conversation.

  <Expandable title="Properties">
    <ParamField path="id" type="string" required>
      Unique ID of the character.
    </ParamField>

    <ParamField path="name" type="string" required>
      Name of the character.
    </ParamField>

    <ParamField path="avatarUrl" type="string" required>
      URL of the character's avatar.
    </ParamField>

    <ParamField path="isNsfw" type="boolean" optional>
      Indicates whether the character is NSFW.
    </ParamField>

    <ParamField path="greeting" type="string" optional>
      The character's greeting.
    </ParamField>

    <ParamField path="persona" type="string" optional>
      Description of the character's personality.
    </ParamField>

    <ParamField path="tags" type="array" optional>
      Tags describing the character.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="regulatory" type="object" optional>
  Regulatory object used in this conversation.

  <Expandable title="Properties">
    <ParamField path="gdpr" type="integer" optional>
      Indicates whether the request is subject to GDPR regulations. (0 = No, 1 = Yes, null = Unknown)
    </ParamField>

    <ParamField path="gdprConsent" type="string" optional>
      The IAB Transparency and Consent Framework (TCF) consent string.
    </ParamField>

    <ParamField path="coppa" type="integer" optional>
      Indicates whether the request is subject to COPPA. (0 = No, 1 = Yes, null = Unknown)
    </ParamField>

    <ParamField path="gpp" type="string" optional>
      Global Privacy Platform (GPP) consent string.
    </ParamField>

    <ParamField path="gppSid" type="array" optional>
      IDs of the GPP sections that apply to this transaction.
    </ParamField>

    <ParamField path="usPrivacy" type="string" optional>
      Signals regarding consumer privacy under US privacy regulations (e.g., CCPA, LSPA).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="variantId" type="string" optional>
  Publisher-provided identifier for the user cohort (for A/B testing).
</ParamField>

<ParamField path="onEvent" type="function" optional>
  Callback triggered when an event occurs. See [Supported events](#supported-events) below.
</ParamField>

<ParamField path="onDebugEvent" type="function" optional>
  Callback for SDK-internal diagnostic events. Receives `(name, data?)` — useful when investigating preload/session behaviour during integration. Off by default.
</ParamField>

## `useAds()` composable

Returns `addMessage`, a forwarder that always routes to the current session. If `<AdsProvider>` swaps the session (e.g. `publisherToken` change), the next call hits the new one automatically.

<ParamField path="addMessage" type="function" required>
  `(message: Message, options?: AddMessageOptions) => void` — register a new chat message with the SDK. The next preload is scheduled automatically.

  `AddMessageOptions` currently exposes one flag:

  <Expandable title="AddMessageOptions">
    <ParamField path="trackOnly" type="boolean" optional>
      When `true`, the preload request still goes out for analytics but no ad will be shown for this message. Use this to suppress ads without losing tracking data.
    </ParamField>
  </Expandable>
</ParamField>

## `Message` shape

<ParamField path="id" type="string" required>
  Unique ID of the message.
</ParamField>

<ParamField path="role" type="string" required>
  Role of the message (`user` or `assistant`).
</ParamField>

<ParamField path="content" type="string" required>
  Message text.
</ParamField>

<ParamField path="createdAt" type="Date" required>
  Timestamp when the message was created.
</ParamField>

## `InlineAd` properties

<ParamField path="messageId" type="string" required>
  Unique ID of the message this ad belongs to.
</ParamField>

<ParamField path="code" type="string" optional>
  Placement code provided during onboarding. Defaults to `'inlineAd'`.
</ParamField>

<ParamField path="theme" type="string" optional>
  Theme of the ad, e.g. `light` or `dark`.
</ParamField>

### Slots

<ParamField path="wrapper" type="slot" optional>
  Render-prop slot that lets you wrap the ad iframe in your own markup. The slot receives the rendered ad as `ad`:

  ```vue theme={null}
  <InlineAd :messageId="m.id">
    <template #wrapper="{ ad }">
      <div class="my-ad-card">{{ ad }}</div>
    </template>
  </InlineAd>
  ```
</ParamField>

## Supported events

### `ad.clicked`

The user has clicked the ad.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="content" type="string">Generated ad content.</ParamField>
  <ParamField path="messageId" type="string">Message ID.</ParamField>
  <ParamField path="url" type="string">Click URL.</ParamField>
  <ParamField path="format" type="string">Ad format.</ParamField>
  <ParamField path="area" type="string">Region of the creative the user clicked (e.g. `'cta'`, `'banner'`).</ParamField>
</Expandable>

### `ad.viewed`

The user has viewed the ad.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="content" type="string">Generated ad content.</ParamField>
  <ParamField path="messageId" type="string">Message ID.</ParamField>
  <ParamField path="format" type="string">Ad format.</ParamField>
  <ParamField path="revenue" type="number" optional>The revenue of the ad (eCPM in USD).</ParamField>
</Expandable>

### `ad.filled`

Ad is available.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="code" type="string">Placement code this ad was matched to.</ParamField>
  <ParamField path="revenue" type="number" optional>The revenue of the ad (eCPM in USD).</ParamField>
</Expandable>

### `ad.no-fill`

Ad is not available.

<Expandable title="Payload">
  <ParamField path="skipCode" type="string">The code indicating the reason why the ad was skipped.</ParamField>
</Expandable>

### `ad.render-started`

Triggered before the first token is received.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `ad.render-completed`

Triggered after the last token is received.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `ad.error`

Triggered when an error occurs.

<Expandable title="Payload">
  <ParamField path="message" type="string">Error message.</ParamField>
  <ParamField path="errCode" type="string">Error code.</ParamField>
</Expandable>

### `video.started`

Triggered when the video playback starts.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `video.completed`

Triggered when the video playback finishes.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `reward.granted`

Triggered when a rewarded-ad reward is granted to the user.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>