SDK integration flow
This is the advanced SDK lifecycle around job creation, decision delivery, generation reporting, and beacons. The default API lifecycle is shorter and lives under /api.
- 1
Import and initialize
WavebirdClientInitialize the client with
baseUrl, servergetApiKeyor browsergetPublishableKey, and optionallydecisionDeliveryplus timing,wrapper_version, and error observation options. - 2
Create a job
After the required stored session permission is current, call
createJob({ job_type: "chat" }). Context, brand safety, and slot hints are optional. An accepted response returnsjob_idandslot_ids; rejected admission is not a fill. - 3
Report generation started
Report model generation start through
reportGeneration(jobId, "started", request). - 4
Retrieve the decision
Retrieve the sponsor decision for the first slot through
getDecision(slotId)usingauto,websocket,polling, or callback-driven delivery. - 5
Continue and finish generation
Continue model generation and then report
finishedor, if needed,failed. - 6
Render fill or handle no-fill
On fill, render
creative, respectconstraints, and useasset_token. The filled creative may also includeclick_through_urlandsponsor_name. On no-fill, react toreasonandcs_declaration. - 7
Send beacons after fill
Send wrapper beacon events such as
rendered,visible_started,visible_ended, orclickedthroughsendBeacon()only with current permission. A complete creative-specific sequence supplies delivery evidence; it does not by itself establish billable revenue, settlement, or a payout.
What goes into `createJob()`
Data flow: The job payload goes to the wavebird runtime. An optional prompt must be permitted by the integration and consent settings. Standard SSP builders use the data firewall signal projection rather than the raw prompt body. This boundary does not cover separate model requests, custom adapters or application logs. Placement, transaction and regulatory fields are checked separately.
job_typeis the only required field.slots_requesteddefaults to1.promptis optional and accepts either a string or an object withtextand an optionaltoken_count_estimate.context.topicis the lightest way to provide matching context without sharing prompt text.consentflags do not replace the current stored session permission required by wavebird_consent projects. TCF/GPP admission remains disabled until an authoritative policy mapping exists. Preserve observed positive Sec-GPC across server hops; keep the app running without ads when admission is denied.brand_safetyandslot_configare optional expansion surfaces for blocking and placement control.decisionDeliverycan beauto,websocket,polling, orcallbackat the client level.callback_urlopts a job into callback delivery even when the client-level mode is not"callback".- Optional fields also include publisher metadata, latency hints, client identifiers, routing hints, and callback settings for advanced delivery flows.
What comes back
- From
createJob()you get accepted job metadata, a typedrate_limit_exceededresult, ornullwhen the SDK falls back silently. - From
getDecision()you get pending or ready decisions, preservingconstraintsandcs_declaration. - From
sendBeacon()you get{ accepted, reason_code }.reportGeneration()always resolves.
node-server.ts
typescript
Choose hosted defaults or package control
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.