Migrate from SDK-first

New wavebird integrations should start with the Server API, use Script Tag for browser-first installs, and keep the SDK as an advanced compatibility layer. Existing SDK integrations can keep running while you move route ownership and docs references to the API-first model.

Priority order

What changes

1. Server API

Use /v1/placements from your backend and /v1/render.js in the frontend when your server owns the flow.

2. Script Tag

Use wavebird.js with a publishable key when the browser should discover slots, render ads, and send beacons directly.

3. Advanced SDK

Keep wavebird for teams that intentionally want package ergonomics or need backwards compatibility during migration.

Compatibility

Route mapping

Old SDK-first surfaceCurrent preferred surfaceMigration note
createJob() + getDecision()POST /v1/placementsKeep SDK code working, but show the one-call placement route in new onboarding.
Raw media renderingGET /v1/render.jsLet the hosted renderer consume placement.render instead of adding image or video DOM yourself.
sendBeacon()POST /v1/beaconsPreserve render, visibility, click, and completion evidence.
/public/browser/v1/activate/v1/browser/activateThe public-browser route remains a compatibility alias.

Steps

Safe migration order

  1. Step 1

    Create or verify secret and publishable keys in the dashboard.

  2. Step 2

    Move new backend snippets to /v1/placements and frontend snippets to /v1/render.js with wavebird.withTurn().

  3. Step 3

    For browser-first pages, replace package bootstrap snippets with Script Tag markup.

  4. Step 4

    Keep existing SDK installs pinned and validate them with test keys before removing package code.

  5. Step 5

    Update docs, runbooks, and partner-facing copy so API appears first, Script Tag second, SDK third.

  6. Step 6

    Confirm logs show placements, decisions, consent, and beacons under the same project before live traffic.

The SDK is not removed. It remains supported as a compatibility and advanced-package path while partner-facing onboarding moves to the API-first sequence.

Review Advanced SDK positioning

Need rollout review?

Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.

Contact the team