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

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.

init(config)

Initializes the global controller, refreshes browser activation, loads public app config, and auto-discovers slots by default.

createJob(options)

Creates a browser job and returns jobId plus slotIds using the compatibility browser flow behind the scenes.

renderAd({ slotId, target, waitMs? })

Polls the canonical /v1/decisions/{slot_id} route, renders banner, clip, or native output, and wires beacons automatically.

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

Fires after init() resolves the active client configuration and browser activation context.

job:created / decision:loaded

Useful for custom debugging, analytics hooks, and sandbox observability.

ad:rendered / ad:empty

Signals whether a slot rendered a creative or resolved as no-fill.

clip:play_started / clip:play_completed / clip:autoplay_blocked

Clip-only playback lifecycle events surfaced by the Stage 1 renderer.

consent:required / consent:submitted

Raised when the built-in wavebird consent flow needs user input or has stored a new consent state.

error

Non-fatal runtime errors surfaced with a stable code and message 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.