Configuration

Copy the saved project configuration from Dashboard. Connect application hooks on your server and browser. Change only documented options.

Connect the app, not another ad stack

The generated files are complete integration templates with explicit connection points. They deliberately fail closed until your app supplies a validated session, durable atomic storage and its model stream.

createPostgresTurnStorage accepts an existing PostgreSQL pool. Run install() once in your normal migration process. Custom stores must serialize each scope/key transition across workers and persist it before returning. An in-memory map or plain read-then-write is not an equivalent adapter.

Use the same trusted session ID for sessionGET, generation, consent and placement. Do not accept another user's browser-supplied session, use the latest global job or store credentials as identifiers.

Quickstart connection points →

Start with the smallest valid placement body

These three fields identify the project, session, and surface. Consent requirements also depend on the project and request: Dashboard-created projects using Test credentials require a current stored consent record in the same authenticated project and session; inline consent is not a substitute. Add context, hints, and overrides only when needed.

Minimal placement request body

placement.json

json

JSON
{  "client_id": "wbproj_...",  "session_id": "sess_...",  "job_type": "chat",  "consent": {    "semantic_targeting": false,    "prompt_shared": false,    "gdpr_applies": true,    "consent_source": "wavebird_consent"  }}

Identity and keys

Project ID (client_id, WAVEBIRD_CLIENT_ID)

Public project identifier used by both browser and server flows to resolve defaults and config. In the dashboard this is the Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_....

Publishable key

Browser-safe key used only for activation-backed traffic. It must be bound to allowed origins.

Secret key

Server-only key for canonical backend calls against /v1/placements, advanced job/decision routes, and /v1/beacons. Use a Server Test Key (sk_test_...) first for Test traffic.

Production dry-run key

Server-only key for pre-live production dry-run checks (sk_dry_...). It selects dry-run mode by credential class; do not add production_dry_run, production_billing_dry_run, billing_suppressed, or production_live_approved to request bodies.

Runtime defaults

Format and label defaults

Preferred formats, slot hints, disclosure labels, and other non-secret defaults are resolved from the authenticated key's project and client_id. Advanced Server API calls can override supported fields such as allowed_formats, timing, bidfloor, publisher, and blocked_categories.

Allowed origins and browser safety

Allowed origins gate publishable-key activation. Browser-safe integration is not just about the key prefix; it depends on server-side origin enforcement.

Change behavior

Config propagation

The generated package options capture the saved configuration at copy time. Recopy the matching files and redeploy after changing those options. Runtime config loading does not rewrite your installed code or select a different package.

Rate limits and CORS

SurfaceKey typeOrigin behaviorLimit behavior
/v1/placements, /v1/jobs, /v1/decisions, /v1/beaconsSecret keyDirect REST uses server credentials. The package separately checks browser-to-publisher publicOrigins.Per-key buckets; 429 includes Retry-After.
/v1/browser/activatePublishable keyThe request origin must match the key's allowed origins.Publishable-key and browser-IP buckets protect activation.
Browser token callsActivation tokenPreflight can succeed for candidate origins; the actual request is still checked against stored project/key state.Separated from secret-key traffic so sandbox and live integrations do not share counters.

Server package options

Names below are createPublisherServer options. Required means the package has no usable default. Keep Dashboard-owned fields aligned with the saved project. REST uses the separate snake_case fields in the endpoint reference.

OptionPurpose and valuesRequired / defaultWho sets it
apiBaseUrlwavebird service URLDefault https://api.wavebird.aiDashboard ENV. Do not redirect secrets to an untrusted host.
clientId / secretKeyProject wbproj_… and its sk_test_ or sk_live_ keyRequired, no default. sk_dry_ is not accepted by this package.Dashboard / server ENV only
preferenceSecretStable signing secret, at least 32 UTF-8 bytesRequired, no defaultServer ENV. Keep across deploys, never in browser.
authorizeValidate the existing authenticated app requestRequired function, fail closedPublisher authentication
publicOriginsExact browser origins allowed to call your backend, including scheme and any non-default portRequired, 1–8 origins. No wildcard or automatic www alias.Dashboard's verified origins via server ENV. Explicit loopback origins are for local development only.
sessionIdForRequest / turnJournalTrusted session and durable turn coordinationOptional only as a pair in low-level API. Required by current generated integration.Publisher hooks + package journal
surfaceId / placementKeySaved placement identityRequiredDashboard
jobTypechat, code, image, voice or agent. Clip is an ad format.RequiredDashboard
localeApp language/localeRequired by the typed interfaceDashboard
timingbefore, during or afterRequired on serverDashboard, same as browser
consentModewavebird_consent or own_cmpRequired on serverDashboard, same as browser
gdprAppliesJurisdiction input, booleanDefaults false when omitted. Use the actual policy value, never infer consent.Dashboard / actual request policy
publisherapp_name, app_domain and categoriesRequiredSaved app identity, not the visitor
allowedFormatsNonempty banner, native, clip listRequired, limited by project eligibilityDashboard
positionHintabove, below, sidebar or betweenPackage configuration; server uses the saved default when omittedPublisher layout; format, timing and size permissions remain project-bound
allowedSizes1–8 unique positive integer sizes, edges ≤4096, optional format restrictionsRequiredDashboard
maxWidth / maxHeightOptional integer caps, 1–8192Defaults to largest saved allowed sizePublisher only when layout requires
responsiveSizeSelectionChoose a supported size within available boundsEnabled unless falseKeep default for responsive layouts
bidfloor / bidfloorCurrencyMinimum bid and three-letter currencyBoth omitted or both supplied. Nonnegative finite amount.Saved project or explicit paired override. Not a guaranteed payout.
blockedCategoriesCategory exclusionsOptional. Omit to retain project policy.Saved policy / stricter supported override
onDiagnosticFixed diagnostic code callbackOptional, no loggerPublisher. Do not log full requests.

Browser adapter options and hooks

Use the generated component so project and server values agree. The browser holds no Server Key or Preference Secret.

Option / hookValue or defaultPublisher responsibility
targetRequired HTMLElementStable visible container with available width
clientId / surfaceId / jobTypeRequired, matching serverKeep Dashboard values
userId / conversationIdRequired app identifiersUse current user/conversation, never credentials
turnBinding / sessionIdturnBinding defaults false. Current generated path sets true with trusted sessionId.Obtain session from authenticated server, rebind on changes
timing / consentModeLow-level defaults during / wavebird_consentUse saved server values, do not rely on a mismatched default
placementEndpoint / consentEndpointLow-level defaults /api/sponsor-slot and /api/sponsor-consentGenerated files explicitly use /api/wavebird/placement and /api/wavebird/consent. Match your authenticated routes.
rendererUrlOnly https://api.wavebird.ai/v1/render.jsUse default official renderer
getFormatOptional auto, banner, native or clip callbackRestrict to saved allowed formats
privacySettingsTargetOptional selectorProvide an accessible way to reopen consent
consentLocale / consentTheme (beta.17)Optional fallback language and bounded theme. Browser language takes priority. Default: English fallback and wavebird styling.See Consent appearance. Styling never changes consent choices or permission.
connectGeneration.requestExisting authenticated model requestForward supplied headers, input validation and abort signal
connectGeneration.consumeExisting stream/output consumeronDelta for progress, onPresented for visible result. Resolve after presentation. A plain-response fallback may omit onPresented in beta.12, beta.13 and beta.14; guard the callback and still display the model result.
setConversation / disposeExplicit lifecycle callsRebind on user/conversation changes, dispose on unmount
grant / deny / withdrawActual user choice onlyUse genuine dialog or own CMP. Never grant at startup.

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team