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

> Props, hooks, components, and events exposed by the React SDK.

## `<AdsProvider>` props

<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()` hook

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

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

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

  ```tsx theme={null}
  <InlineAd
    messageId={m.id}
    wrapper={(ad) => <div className="my-ad-card">{ad}</div>}
  />
  ```
</ParamField>

## `<ErrorBoundary>`

`<InlineAd>` is wrapped in an internal `ErrorBoundary` so a broken ad never crashes the host app. The component is also exported in case you want to wrap your own logic:

```tsx theme={null}
import { ErrorBoundary } from '@kontextso/sdk-react'

<ErrorBoundary>
  <YourComponent />
</ErrorBoundary>
```

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