Reference

window.koah.requestAd(request)

interface Dimensions {
  /** Slot's maximum rendered width in CSS pixels. */
  maxWidth?: number
  /** Slot's maximum rendered height in CSS pixels. */
  maxHeight?: number
}

type ConversationContext = {
  type: 'conversation'
  question: string
  answer?: string
  external_conversation_id?: string
}

type ArticleContext = {
  type: 'article'
  title: string
  content: string
  about?: string
}

type FeedContext = {
  type: 'feed'
  text: string
  source?: string
  description?: string
}

type StaticContext = {
  type: 'static'
}

type AdContext =
  | ConversationContext
  | ArticleContext
  | FeedContext
  | StaticContext

type PreviewFormat =
  | 'card_text_md'
  | 'card_text_sm'
  | 'card_image_md'
  | 'card_image_sm'
  | 'image_side_rail_md'
  | 'poll_md'
  | 'poll_cta_md'
  | 'expandable_md'
  | 'rabbit_hole_md'
  | 'catalog_lg'
  | 'catalog_md'
  | 'catalog_sm'
  | 'quick_pick_md'
  | 'budget_finder_md'

interface AdRequest {
  target: Element
  context: AdContext
  dimensions?: Dimensions
  experimentTag?: string
  slot?: string
  previewFormat?: PreviewFormat
  signal?: AbortSignal
  onFill?: () => void
  onNoFill?: () => void
}

interface AdResult {
  filled: boolean
  fromCache?: boolean
}

type KoahAgeRange =
  | 'unknown' | 'under-13'
  | '13-15' | '16-17' | '18-20' | '21-24' | '25-29' | '30-34' | '35-39'
  | '40-44' | '45-49' | '50-54' | '55-59' | '60-64' | '65-69' | '70-74' | '75+'

type KoahGender = 'unknown' | 'male' | 'female'

type KoahIncomeBracket =
  | 'unknown' | '0-50' | '50-100' | '100-150' | '150-200' | '200+'

declare global {
  interface Window {
    koah: {
      requestAd(request: AdRequest): Promise<AdResult>
      /** @deprecated Retired. Resolves `false`. Use `requestAd`. */
      process(...args: unknown[]): Promise<boolean>
      /** @deprecated Retired. Resolves `false`. Use `requestAd`. */
      processStaticAd(...args: unknown[]): Promise<boolean>
      /** @deprecated Retired. Resolves `false`. Use `requestAd`. */
      generateTextAd(...args: unknown[]): Promise<boolean>
      setAgeRange(range: KoahAgeRange | { min: number; max: number }): void
      setAge(age: number): void
      setGender(gender: KoahGender): void
      setIncomeBracket(bracket: KoahIncomeBracket): void
    }
  }
}

const controller = new AbortController()

window.koah.requestAd({
  target: document.getElementById('ad-slot'),
  context: { type: 'conversation', question, answer },
  signal: controller.signal,
})

// Cancel if user navigates away
controller.abort()

const requestControllers = new Map()

function switchConversation(conversationId) {
  // Cancel previous conversation's pending requests
  requestControllers.get(currentConversationId)?.abort()

  // Create new controller for this conversation
  const controller = new AbortController()
  requestControllers.set(conversationId, controller)

  window.koah.requestAd({
    target: document.getElementById('ad-slot'),
    context: {
      type: 'conversation',
      question,
      answer,
      external_conversation_id: conversationId,
    },
    signal: controller.signal,
  })
}

function KoahAd({ question, answer, conversationId }) {
  const slotRef = useRef(null)
  const requested = useRef(false)

  useEffect(() => {
    // Assumes the SDK script has loaded — see Installation for gating on
    // `window.koah` (or load the script with `defer` instead of `async`).
    if (requested.current || !slotRef.current || !window.koah) return
    requested.current = true

    window.koah.requestAd({
      target: slotRef.current,
      context: {
        type: 'conversation',
        question,
        answer,
        external_conversation_id: conversationId,
      },
    })
    // No abort here: doing so would cancel the request under Strict Mode.
  }, [question, answer, conversationId])

  return <div ref={slotRef} />
}