Advanced SDK

Package-level control for AI ad delivery.

Wavebird connects AI surfaces to programmatic ad delivery. This SDK section documents the released advanced compatibility layer package for teams that want typed control over ad requests, decisions, rendering helpers, consent, generation lifecycle events, and beacons.

Use API docs for hosted defaults. Use this SDK when your product needs direct package control over how ads are requested and rendered on an AI surface.

$ npm install wavebird

Back to API docs →Get your API key →Read SDK quickstart →Troubleshooting →

Prompts and chat history are not sent to ad partners. If prompt text is provided, Wavebird reduces it inside the middleware path before any configured ad-market request is built.

Three Steps

From key to controlled ad delivery.

Choose the control surface

Use the API or Script Tag for hosted defaults, or use wavebird when your app needs direct package-level control.

Compare API paths →

Request the ad opportunity

WavebirdClient lets you create jobs, read decisions, report generation events, and send delivery beacons.

SDK install →

Render where it fits

Render through your own UI, the React helper, the DOM mount helper, or hosted rendering. Inference wait time is one supported placement moment.

Rendering pattern →

The Code

Advanced package example in two blocks.

server.ts

typescript

SERVER

import { WavebirdClient } from "wavebird";const client = new WavebirdClient({  baseUrl: "https://api.wavebird.ai",  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",  decisionDelivery: "polling",  publisher: {    app_name: "MyAIChatApp",    app_domain: "mychatapp.com",    categories: ["IAB19"],  },});// Minimal working call:const { slot_ids } = await client.createJob({  job_type: "chat",});const decision = await client.getDecision(slot_ids[0]);// Pass decision to your frontend

AdSlot.tsx

typescript

WIDGET

import { WavebirdAd } from "wavebird/react";function AdSlot({ decision, sendBeacon }) {  return (    <WavebirdAd      decision={decision}      sendBeacon={sendBeacon}    />  );}// That's it. Rendering, beacon tracking,// and billing are all automatic.

ⓘThe WavebirdAd widget handles the full beacon sequence automatically. You only need to call sendBeacon manually if you build a custom renderer. Beacon billing rules →

Show vanilla JS version ▼

ad-slot.js

typescript

VANILLA

import { mountWavebirdAd } from "wavebird/mount";const unmount = mountWavebirdAd({  target: document.getElementById("ad-slot"),  decision: decision,  sendBeacon: async (req) => {    await fetch("/api/beacon", {      method: "POST",      body: JSON.stringify(req),    });  },});

What You Need

The setup checklist.

✓

A sandbox key from the wavebird dashboard

Create an account, complete onboarding, and start with a sandbox secret key. Secret keys stay server-side; publishable keys are for browser activation from allowed origins.

Start setup and get keys →

✓

Node.js 20+ or a modern browser

✓

A GenAI app that handles user prompts

Chat apps, copilots, coding assistants, vertical AI tools.

Platforms

Supported platforms

Platform	Status	Entry point
Node.js 20+	Supported	wavebird
Browser (React, Vue, Svelte)	Supported	wavebird/react
Browser (vanilla JS)	Supported	wavebird/mount
Next.js (App Router)	Supported	Server: wavebird, Client: /react
React Native	Unsupported	No official test coverage or examples in the current release
Electron	Unsupported	No official test coverage or examples in the current release
Deno	Not supported	-

Performance

Lightweight and non-blocking.

Metric	Value
Bundle size (server, gzip)	7.61 kB
Bundle size (react, gzip)	7.76 kB
Bundle size (mount, gzip)	7.72 kB
Client creation heap delta	304.7 kB
Cold start to first decision	27.87 ms

createJob() and getDecision() are async request methods and do not block the UI thread. The Node SDK has zero external runtime dependencies. The default request timeout is 2000ms, clamped to250..30000ms; the default decision budget is 30000ms.

API Surface

The app-facing surface.

Import	What it does
new WavebirdClient(options)	Initialize with baseUrl + API key
client.createJob(request)	Start a sponsoring slot
client.getDecision(slotId)	Get fill, no-fill, or pending
client.reportGeneration(jobId, ...)	Track model start/finish/fail
client.sendBeacon(request)	Report render/click/visibility
<WavebirdAd /> (React)	Auto-render + auto-track widget
mountWavebirdAd() (vanilla JS)	Same widget, no React required

Full SDK reference →

Request Cadence

One prompt, one job.

Request a new ad when the user sends a new prompt. wavebird does not auto-refresh ads on a timer, and the SDK does not rotate creatives in the background.

Server-side frequency caps still apply. If a wrapper keeps creating jobs without corresponding user activity, wavebird can return no-fill and flag the traffic as anomalous. If you want banner-only behavior, pass allowed_formats: ["banner"] explicitly. Native and clip are opt-in.

Integration Paths

Choose the right integration surface.

Hosted default: Server API

Your backend calls /v1/placements, your frontend loads render.js, and Wavebird owns media sizing, click handling, and beacons.
This is the shortest documented path when you do not need package-level rendering or lifecycle control.

Use Server API default →

Advanced package path: SDK Server Integration

Use this when your team wants WavebirdClient, typed package methods, custom rendering, callback delivery, or explicit control over lifecycle beacons.

Open SDK Server Integration →

Also available: Browser Integration · Callback delivery · Proxy compatibility

All integration patterns →

How You Earn

What becomes billable.

You receive 90% of every verified ad impression.

Early-access rate: wavebird retains 10% as platform fee.

Banner and native

rendered → visible_started → visible_ended ← billable

Clip (video)

rendered → play_started → play_completed ← billable

ⓘThe WavebirdAd widget sends the full sequence automatically. Custom renderers must follow the beacon billing guide. Billing guide →

For the SSP-facing integrity model behind these billing events, read the proof integrity whitepaper →

Get your API key →Read API quickstart →Read SDK quickstart →

Last updated: 2026-06-25

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.