SDK package quickstart

Use this page when you intentionally want package-level control. Create a wavebird account first, complete onboarding, and start with the sandbox secret key from your dashboard. Hosted defaults remain documented under /api/quickstart and /api/patterns/server-api. The SDK quickstart below uses the released wavebird surface.

Default integration lives in the API docs

This page is the package quickstart. If you are adding Wavebird for the first time, use the Server API default instead: backend calls /v1/placements, frontend loads render.js, and wavebird.withTurn() handles the turn lifecycle.

Open API quickstartServer API pattern

SDK prerequisite: dashboard keys

Before this snippet runs, create an account, complete onboarding, and copy the sandbox secret key from your dashboard. Use it as WAVEBIRD_SECRET_KEY on the server. For browser SDK usage, copy a publishable key and configure allowed origins before testing. Switch to your live secret key only when production traffic and any partner path are approved.

Start setup in dashboardOpen dashboardTesting guide

node-server.ts

typescript

NODE ENTRY
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",});const job = await client.createJob({  job_type: "chat",});const decision = job?.slot_ids[0] ? await client.getDecision(job.slot_ids[0]) : null;console.log(decision);

Expand the minimal call

Add privacy controls

Add GDPR, TCF, US privacy, and prompt-sharing choices only when your app needs them.

add-privacy-controls.ts

typescript

PRIVACY
const job = await client.createJob({  job_type: "chat",  consent: {    semantic_targeting: true,    prompt_shared: false,    gdpr_applies: true,    consent_source: "wrapper_cmp",    tcf_consent_string: "CONSENT_STRING",    gpp_string: "DBAB...",    gpp_sections: [7],  },});

Add brand safety

Block categories and advertiser domains without changing the minimal flow.

add-brand-safety.ts

typescript

BRAND SAFETY
const job = await client.createJob({  job_type: "chat",  brand_safety: {    blocked_categories: ["IAB25-3"],    blocked_domains: ["ads.bad.example"],  },});

Add context

Use context.topic when you want matching context without sharing prompt text.

add-context.ts

typescript

CONTEXT
const job = await client.createJob({  job_type: "chat",  context: {    topic: "programming",  },});

Add slot customization

Constrain formats, sizes, position hints, and bidfloors per request.

add-slot-customization.ts

typescript

SLOT CONFIG
const job = await client.createJob({  job_type: "chat",  slot_config: {    allowed_formats: ["banner"],    max_width: 728,    max_height: 90,    position_hint: "above",    bidfloor: 0.5,    bidfloorcur: "EUR",  },});

If you send prompt text

The prompt field is optional. If you send it, the payload goes to the wavebird runtime, where the data firewall extracts only an abstract topic category and the language. These two signals are the only data that can reach a configured partner path. Users' prompts, chat history, and identifiers are never sent to SSPs, DSPs, or advertisers. If you want to understand the full data flow, see How wavebird works and Data Firewall.

Copy the code only after choosing the SDK path and storing your sandbox secret key server-side as WAVEBIRD_SECRET_KEY. Move to Integration flow, Configuration, and the WavebirdClient reference for deeper lifecycle and type details.

  • Shows the smallest working server-side call with job_type only.
  • Constructor-level publisher metadata keeps the request minimal while still sending app identity.

Read next

Integration flowConfigurationWavebirdClient referenceTroubleshooting

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.