Integration FAQ

Find the next step for your setup, code or delivery issue.

Setup

Do I need the SDK to integrate wavebird?

For JavaScript and TypeScript, start with the @wavebirdai/api package and Dashboard files. It connects to the same public API. The older wavebird Advanced SDK is a separate integration, not another name for this package.

View the steps →

What is the recommended browser path?

For an app with a backend, use the server package and its browser adapter. It loads the official renderer. Script Tag is a separate publishable-key path with its own consent and origin requirements.

View the steps →

Why does my domain work with www but not without it?

They are distinct origins. Save the full app URL and verify each origin you actually use. An origin has no page path. localhost and 127.0.0.1 also differ, as do their ports.

View the steps →

How do I verify my app domain?

Open App settings and choose DNS TXT or HTTPS file under Domain verification. Publish the exact current proof, then select Verify. Keep other TXT records and proof files. HTTPS must be public on port 443 with valid TLS, without redirects or login. If DNS is still updating, retry later. A new proof replaces the previous one for that method. Verification enables eligible Test integration, never Live delivery or payouts.

View the steps →

Which key do I need, and can I recover it?

The server integration needs a Server Test Key. Newly stored keys may be revealed through authenticated API Keys controls. Older hash-only keys need rotation if lost. Follow Dashboard's recovery state and never use a masked preview as a credential.

View the steps →

Code

Can I use WordPress, Supabase or another framework?

Yes, through a compatible server runtime or direct REST. The generated Next.js files are not a Supabase Edge Function. Keep your own frontend and model flow, keep the key on the backend, and follow the chosen runtime's API contract.

View the steps →

Why does copied code still reject my requests?

The session and model hooks intentionally deny or throw until connected to your app. Add validated server authentication, a non-credential session ID, durable atomic turn storage and your existing model stream. Do not bypass these checks.

View the steps →

Can an AI coding assistant help?

Use Copy install prompt in Dashboard and the Markdown version of these docs. They explain the selected integration. Add real secrets directly to your server environment, never to the assistant's chat. Review and run the resulting code before release.

View the steps →

Display

What do During and After mean?

During is tied to active generation. A late ad can be discarded when generation finishes. After waits for generation completion and result presentation. Wire the output consumer correctly and never slow the model to give an ad time to load.

View the steps →

Do I need fixed ad dimensions?

Use the project's supported sizes and measure the slot, including space for controls. Padding and sidebars reduce its width. If no size fits, your server returns decision.reason: no_fit before contacting wavebird, so this request does not appear in Test Logs. Increase the available space or leave the slot empty. Keep the input clear.

View the steps →

Why is no ad visible after a successful request?

No-Fill, declined consent and a completed During turn can correctly leave the slot empty. After a fill, check renderer loading, the frame result and slot geometry. A model image or HTTP 200 is not evidence that an ad rendered.

View the steps →

What should happen when a Clip finishes?

Let the package handle natural completion and cleanup. Do not leave the final video frame as a static ad or generate a second completion event. Stop, navigation and turn changes must also clean up the old placement.

View the steps →

Consent

Does wavebird need the conversation or change the answer?

No conversation text is required for the basic placement request. Keep model generation separate. Optional context must follow your consent and privacy settings. Refusing advertising must not block the model response.

View the steps →

What if the user declines or withdraws consent?

Do not request further unauthorized ads. Clear the affected placement, synchronize the real choice and keep the app usable. Do not send a grant automatically or add a second dialog when using your own consent manager.

View the steps →

Live

What must I verify before moving to live keys?

Verify display, consent, cancellation, No-Fill and matching logs on the deployed origin. Then complete the Dashboard's Live requirements and request access. Payout details alone do not authorize delivery or billing.

View the steps →

Why is test revenue zero?

Test and production dry-run traffic are nonpayable. Live earnings depend on approved delivery and qualified measurement, not merely accepted requests. The publisher supplies payout details to receive earnings.

View the steps →

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