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.

Use hosted API docs instead when you want Wavebird to own more of the rendering flow.

For new integrations, use the Server API default first

The hosted production path is documented under Server API: call /v1/placements and render with the hosted render.js flow. Stay on this SDK page when you want typed package control over jobs, decisions, generation reporting, and beacons.

Included today

  • wavebird
  • createJob()
  • getDecision()
  • reportGeneration()
  • sendBeacon()

Verified source

  • README quickstart
  • SDK tests
  • Package smoke

Use this page when you want the complete server-side lifecycle in one place instead of the shorter quickstart snippet.

The example below stays on the direct WavebirdClient path: initialize once, create the job, report generation, read the decision, send a beacon on fill, and finish the lifecycle.

node-server.ts

typescript

ADVANCED
import { WavebirdClient } from "wavebird";const client = new WavebirdClient({  baseUrl: "https://api.wavebird.ai",  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",  publisher: {    app_name: "MyAIChatApp",    app_domain: "mychatapp.com",    categories: ["IAB19"],  },  decisionDelivery: "polling",  options: {    wrapper_version: "wavebird-wrapper/2026.03",  },});const job = await client.createJob({  job_type: "chat",  context: {    topic: "programming",  },});if (job?.slot_ids[0]) {  await client.reportGeneration(job.job_id, "started", {    generation_id: `gen_${job.job_id}`,    model_id: "gpt-4o-mini",  });  const decision = await client.getDecision(job.slot_ids[0]);  if (decision?.fill === true) {    await client.sendBeacon({      beacon_id: `rendered-${Date.now()}`,      asset_token: decision.asset_token,      beacon_type: "rendered",      occurred_at_ms_client: Date.now(),    });  }  await client.reportGeneration(job.job_id, "finished", {    generation_id: `gen_${job.job_id}`,    model_id: "gpt-4o-mini",  });}

Use API Quickstart for the default working setup, SDK Quickstart for the package setup, Integration flow for the step-by-step lifecycle, and WavebirdClient reference for signatures and type-level details.

Choose hosted defaults or package control

Back to API docsContact 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.