AI Ad SDK

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

Quick Start

npm install @ilyashik/ai-ad-sdk

One-line widget (zero UI code)

import { createAdNetwork } from '@ilyashik/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" | "banner"
  lang: 'ru',        // "ru" | "en"
  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) / ads.getRelevantAd(userMessage, aiResponse)

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

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;
  adType: 'relevant' | 'banner';
  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.

What the SDK Handles Automatically

• Sessions & anti-fraud. A stable session identifier is generated on first use and persisted in localStorage; it is attached to every request transparently.
• Geo targeting. Resolved on the server from the client IP — no location data needs to be collected.
• Frequency capping. The backend limits how often the same ad is shown to the same user. Fetch methods may return null — this is expected behavior, not an error.
• Impression tracking. Fired automatically when an ad is received.
• Retries. Transient network errors, 429 Too Many Requests, and 502/503/504 upstream errors are retried with exponential backoff. Each request has a 15-second AbortController timeout so a stalled connection cannot hang the page.
• Active-campaign state. Refreshed in the background every 30 seconds; calls short-circuit instantly when no campaigns are active. On a refresh failure the SDK keeps the cached state and backs off for the same window — it does not retry on every render.

Impression accounting

The SDK fires the impression event the moment getAd/getBanner/mount returns an ad object. This matches industry "impression on serve" semantics and is how every billing model in the Kontezza dashboard is calibrated.

If you want belt-and-braces tracking — for example, you prefetch ads but only paint them on screen later — you can additionally call ads.trackImpression(ad) when the ad becomes visible. The backend de-duplicates impressions per (session_id, ad_id) within the configured frequency-cap window, so this will not double-bill the advertiser.

const ad = await ads.getAd(userMessage, aiResponse);
if (ad && weDecidedToShowIt) {
  ads.trackImpression(ad); // optional — already fired by getAd()
  ads.trackClick(ad);      // when the user clicks
}

For genuinely lazy UIs (where the ad object is created but may never be painted), reach out — we can ship a build with getAd({ autoTrack: false }) for your tenant. Out of the box, every fetch counts as one impression.

TypeScript

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

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