SDKsJavaScript

Use Cases

Learn how to request ads for a variety of application types and contexts using the JavaScript SDK.

Every use case calls the same window.koah.requestAd method — only the context changes to match the surface. See Ad context for what each type means.

Request an ad

Pick the context that matches the surface your ad sits on:

// Chat & assistant surfaces. Pass the question; add the answer once it's ready.
await window.koah.requestAd({
  target: document.getElementById('ad-slot'),
  context: {
    type: 'conversation',
    question: userMessage,
    answer: aiResponse, // optional — omit to fill before the agent responds
  },
})

💡

On conversation surfaces, omit answer if your agent is slow to respond — Koah can fill before the answer is ready.

Multi-turn conversations

Give each ongoing chat a unique external_conversation_id. This links related requests and helps avoid duplicate ads across turns.

await window.koah.requestAd({
  target: chatBubbleEl,
  context: {
    type: 'conversation',
    question: userMessage,
    answer: aiResponse,
    external_conversation_id: 'conv_abc123',
  },
})

In React, fire requestAd once per conversation turn and don't cancel it from useEffect cleanup. See Request Cancellation.

Multiple Ads on One Page

Render multiple ads by calling requestAd once per target element. Each call is ranked independently.

// Inline ad under the latest message
await window.koah.requestAd({
  target: document.getElementById('chat-inline'),
  context: { type: 'conversation', question, answer },
})

// Compact sidebar slot with the same context
await window.koah.requestAd({
  target: document.getElementById('chat-sidebar'),
  context: { type: 'conversation', question, answer },
  dimensions: { maxWidth: 384, maxHeight: 112 },
})

Slots

Tag an ad request with a slot to break down your dashboard reporting by where the ad renders — a feed card, an in-article unit, a chat sidebar. Register your slots in the dashboard first, then pass a registered name as slot on requestAd:

await window.koah.requestAd({
  target: document.getElementById('ad-slot'),
  context: { type: 'article', title, content },
  slot: 'in-article',
})

The same field works for every context, including static placements:

await window.koah.requestAd({
  target: document.getElementById('homepage-ad'),
  context: { type: 'static' },
  slot: 'homepage-hero',
})

Leave slot off and the request rolls up under No slot in reporting.

An unregistered slot is rejected — requestAd resolves with { filled: false } and onNoFill fires. Register the slot in the dashboard before shipping. See Slots for setup, naming rules, and reporting.

Preview Formats (Development)

During development and testing, pass previewFormat to force a specific ad format. This bypasses normal ad selection and returns a specimen ad in the requested format — useful for verifying how each format renders on your page without waiting for real ad inventory.

await window.koah.requestAd({
  target: document.getElementById('ad-slot'),
  context: {
    type: 'conversation',
    question: 'test question',
    answer: 'test answer',
  },
  previewFormat: 'card_image',
})

See Ad formats for a list of preview formats.

previewFormat is for development only. It does not require authentication and always returns a static specimen ad. Do not use it in production — the parameter is ignored for non-demo accounts.