React SDK

Official React SDK for integrating chatbot ads

Official SDK for integrating chatbot ads into your React application.

Quick Integration: Get started in minutes with just a few lines of code. The SDK handles ad fetching, tracking, and display automatically.

Installation

1. Install the package

   npm

   npm install @kovio/chatbot-ad
   
2. Import and use

   import { ChatbotAd } from '@kovio/chatbot-ad'
   
   <ChatbotAd
     publisherId="your-publisher-id"
     keyword="technology,ai"
     theme="dark"
     format="standard"
   />
   

That’s it! The SDK handles everything automatically: fetching relevant ads, tracking impressions & clicks, displaying ads beautifully, and supporting light & dark themes.

API Reference

ChatbotAd Component

publisherId · string · required

Your unique publisher ID from the Kovio dashboard.

Show Where to find your Publisher ID

You can find your publisher ID in the Kovio dashboard after signing up. It’s a unique identifier that links your application to your account.

keyword · string · required

Comma-separated keywords to match ads. The SDK will find the most relevant ad based on these keywords.

Show Keyword Best Practices

• Use 2-4 keywords for best results
• Match keywords to conversation context
• Use specific terms (e.g., “technology,ai” instead of just “tech”)
• Update keywords dynamically based on user queries

Examples:

<ChatbotAd keyword="technology,ai" />
<ChatbotAd keyword="finance,startup,business" />

theme · 'light' | 'dark' · default: "'dark'"

Display theme for the ad. Choose between light and dark themes to match your application’s design.

Show Theme Examples

<ChatbotAd theme="light" />  // Light theme
<ChatbotAd theme="dark" />   // Dark theme (default)

format · 'standard' | 'small' · default: "'standard'"

Ad format type. Choose the format that best fits your layout.

Show Format Details

• standard: Full ad with image, title, message, and button
• small: Compact ad with title and message only

<ChatbotAd format="standard" />  // Full ad
<ChatbotAd format="small" />     // Compact ad

Examples

Basic Usage

import { ChatbotAd } from '@kovio/chatbot-ad'

function MyChatbot() {
  return (
    <div>
      <ChatbotAd
        publisherId="your-publisher-id"
        keyword="technology,ai"
        theme="dark"
        format="standard"
      />
    </div>
  )
}

Multiple Keywords

<ChatbotAd
  publisherId="your-publisher-id"
  keyword="technology,ai,machine-learning,startup"
  theme="dark"
/>

Light Theme

<ChatbotAd
  publisherId="your-publisher-id"
  keyword="technology"
  theme="light"
  format="standard"
/>

Small Format

<ChatbotAd
  publisherId="your-publisher-id"
  keyword="technology,ai"
  theme="dark"
  format="small"
/>

Dynamic Keywords

import { useState } from 'react'
import { ChatbotAd } from '@kovio/chatbot-ad'

function DynamicAd() {
  const [keyword, setKeyword] = useState('technology')

  return (
    <div>
      <input 
        value={keyword} 
        onChange={(e) => setKeyword(e.target.value)} 
      />
      <ChatbotAd
        publisherId="your-publisher-id"
        keyword={keyword}
        theme="dark"
      />
    </div>
  )
}

Features

Ad Formats

Standard Format

The standard format includes:

• Image (if available)
• Title
• Message/description
• “Learn more” button

Best for prominent ad placements in your chatbot interface.

<ChatbotAd format="standard" />

Small Format

The small format includes:

• Title
• Message/description

Best for inline content or compact chat interfaces.

<ChatbotAd format="small" />

Themes

Dark Theme (Default)

Dark background with light text. Perfect for dark mode interfaces.

<ChatbotAd theme="dark" />

Light Theme

Light background with dark text. Perfect for light mode interfaces.

<ChatbotAd theme="light" />

TypeScript Support

The SDK includes full TypeScript definitions:

import { ChatbotAd } from '@kovio/chatbot-ad'

// All props are fully typed
<ChatbotAd
  publisherId="string"      // required
  keyword="string"            // required
  theme?: "light" | "dark"   // optional
  format?: "standard" | "small" // optional
/>

TypeScript definitions are included automatically with the package. No additional @types package needed.

Advanced Usage

Custom Hooks

For advanced use cases, you can use the underlying hooks:

Show useKovioAd Hook

import { useKovioAd } from '@kovio/chatbot-ad'

function CustomAd() {
  const { ad, loading, error } = useKovioAd({
    publisherId: 'your-publisher-id',
    keyword: 'technology,ai',
    theme: 'dark',
    format: 'standard'
  })

  if (loading) return <div>Loading ad...</div>
  if (error) return <div>Error loading ad</div>
  if (!ad) return null

  // Custom rendering
  return (
    <div className="custom-ad">
      <h3>{ad.title}</h3>
      <p>{ad.message}</p>
      <a href={ad.url}>Learn more</a>
    </div>
  )
}

React Native

The SDK also works with React Native:

Show React Native Example

import { ChatbotAd } from '@kovio/chatbot-ad'

function App() {
  return (
    <View>
      <ChatbotAd
        publisherId="your-publisher-id"
        keyword="technology,ai"
        theme="dark"
        format="standard"
      />
    </View>
  )
}

Error Handling

The SDK handles errors gracefully. If no ad is available, the component renders nothing. Network errors are logged to the console, and invalid props are validated with helpful error messages.

Best Practices

Use Relevant Keywords

Match keywords to the conversation context. Use specific terms that relate to what the user is discussing.

Choose Appropriate Format

Use standard for prominent placements, small for inline content. Consider your layout and user experience.

Match Your Theme

Use light or dark to match your app’s design. This ensures ads feel native to your application.

Update Keywords Dynamically

Change keywords based on user conversation context. This improves ad relevance and click-through rates.

Troubleshooting

Ad not showing?

1. Check publisher ID - Verify your publisher ID is correct
2. Check keywords - Ensure keywords are relevant and properly formatted
3. Check console - Look for error messages in the browser console
4. Verify network - Ensure your app can reach the Kovio API

TypeScript errors?

Make sure you have TypeScript installed and the SDK types are being recognized. The SDK includes type definitions automatically.

Component not rendering?

• Check that all required props are provided
• Verify the component is imported correctly
• Ensure React is properly installed and configured

Support

For more information, visit the main documentation or contact support.