Patterns

The SDK supports multiple integration styles for teams that want package-level control in app code. Use SDK Server Integration when you want typed lifecycle methods; use hosted API docs when you want Wavebird to own more of the rendering flow.

Quick answer

If you are still choosing an integration model, start with the API quickstart. If you are intentionally using the SDK, start with SDK Server Integration because it covers the package surface around jobs, decisions, generation events, and beacons.

Use the other pages as specialized follow-ups: browser for Browser Integration, callback for server-side decision handoff, and proxy compatibility for systems that stay at the HTTP boundary.

Choose your path

SDK reading order

SDK Server Integration

ADVANCED

Direct Node/server usage of wavebird and WavebirdClient for job creation, decision reads, generation reporting, and beacon sending.

Use it when you want the released package surface with typed lifecycle methods and direct control over ad requests and beacons.

wavebird
createJob()
getDecision()

SDK Browser Integration

TESTED

Direct browser usage of wavebird/browser with the same WavebirdClient surface.

It fits when you explicitly need browser-side package orchestration with a publishable key and activation handshake, rather than the Script Tag or hosted-renderer path.

wavebird/browser
decisionDelivery: "auto"
getPublishableKey() or publishableKey

Callback delivery

ADVANCED

A server-side path where wavebird posts the decision to a callback_url.

It fits apps that want signed callback-style decision delivery and control over callback handling on the server side.

decisionDelivery: "callback"
callback_url in createJob()
x-csl-signature at the callback boundary

Proxy compatibility

COMPATIBLE

An HTTP/API path where the app sends OpenAI-compatible or Anthropic-compatible requests directly to wavebird proxy routes.

It fits systems that already emit upstream-shaped HTTP requests and do not want to start with WavebirdClient.

/v1/proxy/openai/v1/chat/completions
/v1/proxy/anthropic/v1/messages
direct HTTP instead of WavebirdClient

Read this section in context

If you are new to Wavebird, compare the hosted API path and the SDK package path first. Stay here when you already chose the package layer on purpose and the SDK package layer is the right fit.

Open API quickstart Open SDK quickstart Review Integration flow Check Configuration Open WavebirdClient reference

Graceful degradation

SDK Server Integration

Choose hosted defaults or package control

Back to API docs Contact the team

These pages document the package layer for teams that choose wavebird to control ad requests, decisions, rendering helpers, consent, and beacons directly. Use the API docs for hosted defaults, and use contact only when you want rollout review, enterprise coordination, or help with non-standard integration constraints. Beacon billing rules live in SDK Concepts.