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 direct HTTP calls to /v1/jobs, /v1/decisions/{slot_id}, and /v1/beacons when your backend 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()POST /v1/jobsKeep SDK code working, but show direct REST in new onboarding.
getDecision()GET /v1/decisions/{slot_id}Use the same slot identifier returned by job creation.
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/jobs, /v1/decisions, and /v1/beacons.

  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 jobs, 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?

Contact the team

Start in the dashboard, choose Script Tag or Server API, and use contact only when you need rollout review, enterprise coordination, or non-standard integration help. Billing beacon rules live in the API concepts guide.