Skip to main content
We are preparing a new v4 release of the React Native SDK. The documentation below covers the current shipping version — once v4 lands, this page will be updated.

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 @react-native-community/netinfo

​
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 { View } from 'react-native'
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-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={{
        coppa: 0,
        // ... other regulatory properties
      }}
      onEvent={({ name, code, payload }) => {
        // process events
      }}
    >
      <TheRestOfYourApplication />
    </AdsProvider>
  )
}

​
3. Set up IFA (Identifier for Advertisers)

  • iOS: add NSUserTrackingUsageDescription to ios/<YourApp>/Info.plist. The SDK auto-prompts for ATT and reads IDFA from there.
  • Android: the SDK adds the com.google.android.gms.permission.AD_ID permission via manifest merger automatically — no changes to your AndroidManifest.xml required.
See IFA & ATT for the full setup — required keys, prompt-timing gotchas, and how to manage the prompt yourself.

​
4. Set up SKAdNetwork (iOS only)

Add the SKAdNetwork identifiers we provide during onboarding to ios/<YourApp>/Info.plist. The SDK reads them and forwards them on every /init so DSPs can measure conversions. See SKAdNetwork for the full guide.

​
5. 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 (
    <View>
      {messages.map((m) => (
        <View key={m.id}>
          <Message message={m} />
          <InlineAd code="<your-code>" messageId={m.id} />
        </View>
      ))}
    </View>
  )
}

​
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
Character object used in this conversation.
​
regulatory
object
Regulatory compliance information.TCF (Transparency and Consent Framework) signals — gdpr and gdprConsent — are handled automatically by the SDK if you have a TCF-compliant CMP (Consent Management Platform) integrated in your app. You do not need to set these manually.
​
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

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