Type and runtime reference

data-client-id

Required. Public client identifier for the app whose server-side config should load.

data-publishable-key

Required in production. Browser-safe pk_publishable_* key bound to your allowed origins.

data-session-id

Optional stable session identifier for consent, pacing, and future frequency controls.

data-job-type

Optional product hint. Supported values are chat, code, image, voice, and agent.

data-locale

Optional locale hint for creative selection and disclosures, for example en-US or de-DE.

data-prompt-topic / data-prompt-text

Optional contextual hints passed into the initial job request.

data-native-template

Optional native renderer preset. Supported values are default and compact.

data-timing

Optional timing hint. Supported values are during, before, and after.

data-api-base-url

Optional override for non-production environments. Defaults to https://api.wavebird.ai.

data-auto-discover-slots

Optional. Set false if you want to call renderAd() manually instead of auto-discovering [data-wavebird-slot] targets.

data-wavebird-slot

Marks an element as an auto-discovered render target for the next available slot.

data-wavebird-position

Optional slot placement hint. Supported values are above, below, sidebar, and between.

data-wavebird-max-width / data-wavebird-max-height

Optional sizing constraints used when the renderer reserves space for banner, clip, or native placements.

data-wavebird-formats

Optional comma-separated format hint such as banner,native or clip.

data-wavebird-prompt-topic / data-wavebird-prompt-text

Optional per-slot prompt hints when different placements should use different sponsor context.

data-wavebird-timing

Optional per-slot timing hint. Supported values are during, before, and after; a resolved decision also writes its timing to this attribute.

init(config)

Initializes the global controller. Config requires clientId and accepts publishableKey, sessionId, apiBaseUrl (default https://api.wavebird.ai), jobType, locale, promptTopic, promptText, timing, nativeTemplate (default or compact), nativeStyles ({ card, media, copy, label, sponsor, title, description, cta }), and autoDiscoverSlots (defaults true).

createJob(options)

Creates a browser job and returns jobId plus slotIds. Options are sessionId, jobType, locale, promptTopic, promptText, timing, slotHint ({ position, maxWidth, maxHeight, allowedFormats, bidfloor, bidfloorCurrency, timing }), and slotsRequested.

renderAd({ slotId, target, waitMs? })

Polls the canonical /v1/decisions/{slot_id} route, renders banner, clip, or native output, and wires beacons automatically. waitMs defaults to 1500; it makes at most four attempts with a 500 ms delay between pending attempts.

setConsent(tcfString)

Seeds a stored TCF string for advanced custom consent flows before the next createJob call.

on(event, handler)

Subscribes to lifecycle events such as ready, ad:rendered, consent:required, and error.

ready

Payload: { clientId: string; apiBaseUrl: string }. Fires after init() stores the active configuration.

job:created

Payload: { jobId: string; slotIds: string[] }.

decision:loaded

Payload: { slotId: string; status: string; metadata?: { timing: "during" | "before" | "after" } }.

ad:rendered

Payload: { slotId: string; format: "banner" | "clip" | "native"; metadata?: { timing: "during" | "before" | "after" } }.

ad:empty

Payload: { slotId: string }.

clip:play_started

Payload: { slotId: string }.

clip:play_completed

Payload: { slotId: string }.

clip:autoplay_blocked

Payload: { slotId: string }.

consent:required

Payload: { clientId: string; sessionId: string }.

consent:submitted

Payload: { clientId: string; sessionId: string; decision: "personalized" | "basic" | "custom" }.

error

Payload: { code: string; message: string; cause?: unknown }. Non-fatal runtime errors for debugging.