Type and runtime reference

Server Test Key (sk_test_...)

Backend-only credential for Test/Sandbox requests. Test/Sandbox traffic, validation diagnostics, render signals, and proof signals are non-billable.

Server Production Dry-run Key (sk_dry_...)

Backend-only credential for non-billable pre-live dry-run. Production dry-run is selected by credential class, not by request fields.

Server Production Key

Backend-only credential for approved live traffic after Dashboard live readiness, SSP readiness, payout requirements, and live approval gates are complete.

Browser Publishable Key

Browser credential for Script Tag or activation flows with allowed origins. Browser Publishable Keys are separate from server secrets and cannot be used for server endpoints.

One-time server secret visibility

Raw server secrets are shown only once after create or rotate. Existing masked server-secret previews identify a key but are not usable credentials. Do not send production_dry_run, production_billing_dry_run, billing_suppressed, or production_live_approved in request bodies.

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. Stage 1 supports 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.

Per-key limits

All canonical v1 routes enforce per-key rate limits with burst and sustained buckets.

Browser IP limits

Activation-backed browser traffic adds looser per-IP shaping on top of the publishable-key limit.

429 behavior

Rate-limited responses include the standard Retry-After header and the canonical error envelope.