Server integration
Keep credentials and request authority on your backend. Use the package for a supported runtime, or implement the REST contract directly.
Choose the runtime path
For Next.js, use Dashboard's complete JavaScript or TypeScript files and the package Quickstart. Python uses its separate FastAPI guide. WordPress with a Supabase backend needs a compatible adapter or direct REST. Next.js route files cannot be pasted into an Edge Function.
Connect generation and presentation
Wrap the actual model invocation with withGeneration on the server and connectGeneration in the browser. Preserve authentication, input validation, the model's response and cancellation. Merge the supplied generation headers into your same-origin request.
Forward onDelta only for real text deltas. Call onPresented after the result is actually displayed. After waits for completion and presentation, not merely response headers. Pass the same AbortSignal and never delay the model to make an ad visible.
On conversation changes call setConversation; on unmount call dispose. Follow the selected format and timing. Clip cleans up at its natural end or when its valid placement window ends.
Synchronize the real consent choice
Use the project's configured wavebird dialog or Own CMP profile. Record the current conversation's actual decision before requesting a placement. Keep consent revisions and session binding consistent.
If consent is missing, expired or withdrawn, keep the model usable and the slot empty. Do not replay a grant, rename Own CMP metadata as a wavebird decision or remove privacy signals.
Direct REST responsibilities
Use a server key for POST /v1/placements?wait_ms=1500. The bounded wait may return fill, No-Fill or an unresolved response. Treat these separately and keep the primary model stream independent.
A fill has a placement and decision.fill: true. Pass the validated placement, decision and authoritative consent to the official renderer while permission is current. Retain its cleanup function. For No-Fill, hide the empty slot. For a failed frame, preserve the fixed error category before cleanup.
Use test_outcome=no_fill only with a Server Test Key for deterministic No-Fill checks. Production keys reject it. withTurn() belongs to Script Tag and is not a REST requirement.
Allow the official renderer
Load https://api.wavebird.ai/v1/render.js directly. Allow the required https://api.wavebird.ai origin in the app's script-src, frame-src and connect-src directives. Do not proxy signed creative frames or weaken unrelated security rules.
Let the renderer report measurement
The hosted renderer sends browser beacons to /public/wrapper/v1/beacons. Do not fabricate render, visibility or completion events.
Direct /v1/beacons integrations require the issued asset token, a fresh occurred_at and an idempotent beacon_id. Keep tokens out of logs and debugging output.
Complete the separate Live requirements
Server Test Keys produce nonpayable traffic. Current publisher packages accept Test and Live server keys, not sk_dry_ keys. Production Dry-run requires the compatible REST path.
Live delivery requires the Dashboard's actual approval and payout prerequisites. Never add internal billing or approval flags to request bodies. Completing the integration or entering payout details alone does not activate Live ads.
Need help with your integration?
Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.