React Native Demo Project

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

Requirements

  • React Native: 0.73.2 or later

Getting started

1. Installation

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

# Install required peer dependencies
npm install react-native-device-info react-native-webview

Upgrading from v1.x

If you are upgrading from v1.x to v2.x, note that react-native-device-info and react-native-webview are now required as separate peer dependencies. Install them with:
npm install react-native-device-info react-native-webview

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

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

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

  return (
    <AdsProvider
      publisherToken="<publisher-token>"
      messages={messages}
      userId="<user-id>"
      conversationId="<conversation-id>"
      enabledPlacementCodes={['<code>']}
      character={{
        id: '<character-id>',
        name: '<character-name>',
        avatarUrl: '<character-avatar-url>'
      }}
    >
      <TheRestOfYourApplication />
    </AdsProvider>
  )
}

3. Show your first ad

An ad slot is the element or place in your interface where an ad will be displayed. During onboarding, you will receive a code that you need to use for each ad slot or ad format you want to display. 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).
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.
advertisingId
string
Device-specific identifier (IDFA on iOS, GAID on Android).
vendorId
string
Vendor identifier (IDFV on iOS).
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.

reward.granted

Triggered when the user receives a reward.

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');
    }
  }}
/>