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.

Package Quickstart →Framework and language paths →

Connect the real app session

Validate the signed-in user on every backend operation. Keep the server key, preference secret and project ID in server configuration. The browser's project, format or session values are not authority.

Use a non-credential session identifier bound to the actual conversation. Connect the package's durable atomic turn journal, never a shared demo ID or the last job of a session. Reject cross-user and obsolete turns.

Hooks, fields and defaults →

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.

Timing and formats →

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.

Placement examples and contract →Renderer contract →

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.

Beacon rules →

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.

Live checklist →

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team