SDKsJavaScript

Migrate to v2

Replace the legacy process, processStaticAd, and generateTextAd calls with one requestAd call.

The v1 methods are deprecated as of September 1, 2026. They continue to work, but new formats and features ship only on requestAd. Most call sites change only a few lines — or copy the prompt below and let a coding agent migrate for you.

Prompt for coding agents

I use Koah's legacy v1 JavaScript snippet methods (window.koah.process, processStaticAd, or generateTextAd). Migrate my integration to the v2 requestAd API. Read https://docs.koahlabs.com/sdk/javascript/migration and follow its instructions.

What changes

Aspect	v1	v2
Methods	`process`, `processStaticAd`, `generateTextAd`	One method: `requestAd`
Placement	Dashboard-registered CSS selectors, used when you do not pass `target`	A required `target` element in every call. No dashboard step.
Content	An `adType` string (`'suffix'`, `'prefix'`, …) plus positional arguments	A `context` object (`conversation`, `article`, `feed`, or `static`)
Return value	`Promise<boolean>`	`Promise<AdResult>`: `{ filled: boolean, fromCache?: boolean }`
Sizing	`size: 'small' \| 'medium'`	`dimensions: { maxWidth, maxHeight }`. `requestAd` ignores `size`. Replace it.
Slot tag	`options.slotId`: a free-form string, appended to the registered selector	Removed. The `target` element sets the placement. Pass a registered `slot` name for reporting.
Experiment tag	`options.experimentTag`	`experimentTag` (unchanged)

The script tag does not change. Keep the same <script async src="https://app.koah.ai/js?token=<YOUR_PUBLISHER_ID>"></script> tag.

Placement: from registered selectors to a target element

v1: If you do not pass target, the snippet finds the CSS selectors you registered in the dashboard. It puts the ad in the last matching element.
v2: Pass the target element in every call. You can use any element. You do not register selectors in the dashboard.

slot in v2 is not the v1 selector concept. slot is an optional name for dashboard reporting by placement. Register a slot name in the dashboard before you use it. If the name is not registered, the request resolves { filled: false } and calls onNoFill. Do not rename v1 slotId values to slot. See Slots.

Migrate each call

Chat

window.koah.process(userMessage, aiResponse, 'suffix')

answer is optional. Omit it to fill the ad before the model responds.

See Use Cases for multi-turn conversations.

Article

window.koah.generateTextAd({
  contextType: 'article',
  context: {
    title: '10 Tips for Better Code',
    content: 'Writing clean code starts with naming...',
    about: 'Software engineering best practices',
  },
  options: { target: document.getElementById('ad-slot') },
})

The context fields do not change. For content, send an excerpt of 500 to 1000 characters. Do not send the full article body.

See Use Cases for more article examples.

Feed

window.koah.generateTextAd({
  contextType: 'feed',
  context: {
    text: 'Check out this amazing recipe!',
    source: 'Cooking Community',
    description: 'A community for food lovers',
  },
  options: { target: document.getElementById('ad-slot') },
})

source and description are optional in v2.

See Use Cases for more feed examples.

Static

window.koah.processStaticAd({
  target: document.getElementById('ad-slot'),
})

Pass context: { type: 'static' } for static placements.

Update the return value

const filled = await window.koah.process(userMessage, aiResponse, 'suffix')

Replace boolean checks with the filled field. onFill and onNoFill work the same in both versions.

Size the slot

Replace size with dimensions. requestAd ignores size.

v1 `size`	v2 `dimensions`
`'small'`	`{ maxWidth: 384, maxHeight: 112 }`
`'medium'`	`{ maxWidth: 1440, maxHeight: 550 }`

Contain the ad

💡

Put the target element in a container that has max-width, max-height, and overflow: hidden. Pass the same limits as dimensions. The ad uses the width of its container. dimensions excludes formats that are larger than those limits. If the ad is larger than the container, overflow: hidden clips it so the page layout does not move.

<div style="max-width: 480px; max-height: 300px; overflow: hidden">
  <div id="ad-slot"></div>
</div>

await window.koah.requestAd({
  target: document.getElementById('ad-slot'),
  context: { type: 'conversation', question: userMessage, answer: aiResponse },
  dimensions: { maxWidth: 480, maxHeight: 300 },
})

If your slot can stretch, omit dimensions. More formats can then be selected. If you pass dimensions smaller than 240 × 72, requestAd returns { filled: false } and calls onNoFill with no network request.

See Appearance → Sizing and Format Bounds.

Checklist

v1 and v2 methods are both available on window.koah. Convert one call site at a time.

Keep the script tag as is.
Replace each process, processStaticAd, and generateTextAd call with requestAd.
Pass the target element in every call.
Replace size with dimensions, or pass neither.
Replace boolean result checks with result.filled.