Skip to main content

React Demo Project

See how easy it is to integrate high-performance ads into your React app using our lightweight SDK.

​
Requirements

  • React: 18.3.1 or later

​
Getting started

​
1. Installation

To get started, you will need to set up a publisher account to get a publisherToken and code.
npm install @kontextso/sdk-react

​
2. Initialize AdsProvider

The AdsProvider handles all data-fetching logic and must have access to the chat messages. Place it high enough in your component tree so it can contain all ad placements. 
import * as React from 'react'
import { useState } from 'react'
import { AdsProvider } from '@kontextso/sdk-react'

interface Message {
  id: string
  role: 'user' | 'assistant'
  content: string
  createdAt: Date
}

function App() {
  const [messages, setMessages] = useState<Message[]>([])

  return (
    <AdsProvider
      publisherToken='<your-publisher-token>'
      messages={messages}
      userId='user-1234'
      conversationId='conv-5678'
      enabledPlacementCodes={['inlineAd']}
      character={{
        id: 'character-1234',
        name: 'John Doe',
        avatarUrl: 'https://example.com/avatar.png',
        greeting: 'Hello, how can I help you today?'
      }}
      regulatory={{
        gdpr: 1,
        // ... other regulatory properties
      }}
      onEvent={({ name, code, payload }) => {
        // process events
      }}
    >
      <TheRestOfYourApplication />
    </AdsProvider>
  )
}

​
3. Show your first ad

An ad slot is a designated area in your UI where an ad can be rendered. In most cases, it appears below a chat message. During onboarding, you’ll receive a unique code for each ad slot you plan to use. Copy the markup <InlineAd /> and place it in your application where it should be rendered. Don’t forget to assign messageId as a unique identifier. For example, if you have a MessageList component, you can show an ad after each message like this (every message will have a unique ad displayed because of messageId). 
function MessageList({ messages }: { messages: Message[] }) {
  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <Message message={m} />
          <InlineAd code='<your-code>' messageId={m.id} />
        </div>
      ))}
    </div>
  )
}

​
API documentation

​
AdsProvider properties

​
publisherToken
string
required
Your unique publisher token.
​
messages
array
required
List of messages between the assistant and the user.
​
userId
string
required
Unique identifier that remains the same for the user’s lifetime (used for retargeting and rewarded ads).
​
userEmail
string
Email of the user.
​
conversationId
string
required
Unique ID of the conversation.
​
enabledPlacementCodes
array
required
Placement codes enabled for the conversation. Example: ['inlineAd'].
​
character
object
required
Character object used in this conversation.
​
regulatory
object
Regulatory object used in this conversation.
​
variantId
string
Publisher-provided identifier for the user cohort (for A/B testing).
​
onEvent
function
Callback triggered when an event occurs. See Supported events for more details.
​
isDisabled
boolean
Flag indicating if the ads are disabled.Note: This does not disable the display of old ads; that behavior is controlled by staleAdsHandling.
​
staleAdsHandling
string
Determines how stale ads (ads not linked to the latest message) are handled.
  • preserve - keep displaying the last anchored ad until it’s replaced by a new ad
  • hide (default) - hide the ad when it becomes stale

​
InlineAd properties

​
code
string
required
Placement code provided during onboarding.
​
messageId
string
required
Unique ID of the message.
​
theme
string
Theme of the ad, e.g. light or dark.
​
wrapper
function
Wrapper function to wrap the ad content.

​
Supported Events

​
ad.clicked

The user has clicked the ad.

​
ad.viewed

The user has viewed the ad.

​
ad.filled

Ad is available.

​
ad.no-fill

Ad is not available.

​
ad.render-started

Triggered before the first token is received.

​
ad.render-completed

Triggered after the last token is received.

​
ad.error

Triggered when an error occurs.

​
video.started

Triggered when the video playback starts.

​
video.completed

Triggered when the video playback finishes.

​
Guides

​
Controlling when ads load

You can fine-tune ad frequency by controlling when new messages are passed into AdsProvider. This allows you to adjust the ratio of ads to messages dynamically.

​
Handling no-fill events

You can notify when the ad is not available by using the onEvent callback. 
<AdsProvider
  // ...
  onEvent={({ name, payload }) => {
    if (name === 'ad.no-fill') {
      console.log('Ad is not available');
    }
  }}
/>