AI Ad SDK

Contextual advertising SDK for AI applications. Show relevant ads based on conversation context.

Quick Start

npm install ai-ad-sdk

One-line widget (zero UI code)

import { createAdNetwork } from 'ai-ad-sdk';

const ads = createAdNetwork({ apiKey: 'your-api-key' });

// After each AI response — renders ad automatically:
await ads.mount('#ad-container', { userMessage, aiResponse });

<div id="ad-container"></div>

That's it. The SDK fetches the ad, renders a styled block with "Sponsored" label, and tracks impressions and clicks automatically.

Manual control (custom UI)

const ad = await ads.getAd(userMessage, aiResponse);
if (ad) {
  console.log(ad.title, ad.text, ad.url);
  ads.trackClick(ad); // call when user clicks
}

Via script tag

<script src="https://api.kontezza.com/static/ai-ad-sdk.umd.js"></script>
<script>
  const ads = createAdNetwork({ apiKey: 'your-api-key' });
  ads.mount('#ad-container', { userMessage, aiResponse });
</script>

API

createAdNetwork(options)

| Option | Type | Required | Description | |-----------|---------|----------|--------------------------------| | apiKey | string | yes | Your API key | | baseUrl | string | no | Custom backend URL | | debug | boolean | no | Enable console logging |

ads.mount(container, context, options)

All-in-one: fetches an ad and renders it into the container. Returns the ad object or null.

await ads.mount('#ad-slot', {
  userMessage: 'Помоги с презентацией',
  aiResponse: 'Рекомендую использовать шаблоны...'
}, {
  type: 'relevant',  // "relevant" | "vector" | "banner"
  lang: 'ru',        // "ru" | "en"
  showScore: false,   // show relevance score badge
  linkText: 'Подробнее →'
});

ads.renderAd(container, ad, options)

Render a previously fetched ad object into a container. Useful when you want to control when/how the ad is fetched.

const ad = await ads.getAd(userMessage, aiResponse);
if (ad) {
  ads.renderAd('#ad-slot', ad, { lang: 'en', linkText: 'Learn more →' });
}

ads.getAd(userMessage, aiResponse)

Returns a relevant ad based on conversation context, or null. Impression is tracked automatically.

ads.getVectorAd(userMessage, aiResponse)

Direct vector search (BGE-M3, no LLM summarization). Faster, good for high-frequency calls.

ads.getBanner()

Returns a random banner ad from the active banner campaign, or null.

ads.trackClick(ad)

Track a click event. Called automatically when using renderAd/mount and user clicks the link. Call manually if using custom UI.

Ad Object

{
  id: string;
  campaignId: string;
  title: string;
  text: string;
  url: string;
  imageUrl: string;
  category: string;
  score: number | null;
  adType: 'relevant' | 'banner' | 'vector';
  design: {
    bgColor: string;     // publisher's bg color
    borderColor: string;  // publisher's accent color
  };
}

Design Customization

Ad colors are controlled by the publisher in the Kontezza dashboard. The renderAd/mount methods automatically apply design.bgColor and design.borderColor. Text color adapts to light/dark backgrounds.

TypeScript

Full TypeScript definitions included (index.d.ts).

import { createAdNetwork, Ad, RenderOptions } from 'ai-ad-sdk';