Integration flow
The public API flow is intentionally small. Browser paths add activation. Server paths use /v1/placements. The default frontend loads render.js and lets Wavebird own media rendering and beacons.
1. Load project context
Resolve client_id and the right key class for the surface: publishable key for the browser path, secret key for the backend path.
2. Activate the browser when needed
Script Tag or advanced browser integrations exchange the publishable key for an origin-bound activation token before runtime calls.
3. Create a placement
Call POST /v1/placements from your backend. The request can stay minimal or carry prompt hints, slot hints, and overrides.
4. Render the decision
The placement response is either pending/no-fill or a fill with placement.render. Load render.js and let the hosted renderer mount the creative frame.
5. Disclose and finish
Keep sponsor disclosure visible and let the turn lifecycle preserve the required viewability window before cleanup.
6. Send beacons
Record rendered, visibility, click, or clip-completion events so diagnostics and billing evidence stay complete.
Script Tag path
Handles activation, config loading, slot discovery, consent prompting, rendering, and beacon wiring for you.
Server API path
Keeps request configuration on your backend. Call /v1/placements, then wrap chat work with wavebird.withTurn so the hosted renderer owns media, sizing, and beacons.
Need rollout review?
Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.