npm package: @ilyashik/ai-ad-sdk
Description: Contextual advertising SDK for AI applications
Latest version: 2.3.0

# AI Ad SDK

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

## Quick Start

```bash
npm install ai-ad-sdk
```

### One-line widget (zero UI code)

```javascript
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 });
```

```html
<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)

```javascript
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

```html
<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`.

```javascript
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.

```javascript
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

```typescript
{
  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`).

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