wavebird logo

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 @csl/wrapper-sdk 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