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.
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
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
| Surface | Key type | Origin behavior | Limit behavior |
|---|---|---|---|
/v1/placements, /v1/jobs, /v1/decisions, /v1/beacons | Secret key | Direct REST uses server credentials. The package separately checks browser-to-publisher publicOrigins. | Per-key buckets; 429 includes Retry-After. |
/v1/browser/activate | Publishable key | The request origin must match the key's allowed origins. | Publishable-key and browser-IP buckets protect activation. |
| Browser token calls | Activation token | Preflight 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.
| Option | Purpose and values | Required / default | Who sets it |
|---|---|---|---|
| apiBaseUrl | wavebird service URL | Default https://api.wavebird.ai | Dashboard ENV. Do not redirect secrets to an untrusted host. |
| clientId / secretKey | Project wbproj_… and its sk_test_ or sk_live_ key | Required, no default. sk_dry_ is not accepted by this package. | Dashboard / server ENV only |
| preferenceSecret | Stable signing secret, at least 32 UTF-8 bytes | Required, no default | Server ENV. Keep across deploys, never in browser. |
| authorize | Validate the existing authenticated app request | Required function, fail closed | Publisher authentication |
| publicOrigins | Exact browser origins allowed to call your backend, including scheme and any non-default port | Required, 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 / turnJournal | Trusted session and durable turn coordination | Optional only as a pair in low-level API. Required by current generated integration. | Publisher hooks + package journal |
| surfaceId / placementKey | Saved placement identity | Required | Dashboard |
| jobType | chat, code, image, voice or agent. Clip is an ad format. | Required | Dashboard |
| locale | App language/locale | Required by the typed interface | Dashboard |
| timing | before, during or after | Required on server | Dashboard, same as browser |
| consentMode | wavebird_consent or own_cmp | Required on server | Dashboard, same as browser |
| gdprApplies | Jurisdiction input, boolean | Defaults false when omitted. Use the actual policy value, never infer consent. | Dashboard / actual request policy |
| publisher | app_name, app_domain and categories | Required | Saved app identity, not the visitor |
| allowedFormats | Nonempty banner, native, clip list | Required, limited by project eligibility | Dashboard |
| positionHint | above, below, sidebar or between | Package configuration; server uses the saved default when omitted | Publisher layout; format, timing and size permissions remain project-bound |
| allowedSizes | 1–8 unique positive integer sizes, edges ≤4096, optional format restrictions | Required | Dashboard |
| maxWidth / maxHeight | Optional integer caps, 1–8192 | Defaults to largest saved allowed size | Publisher only when layout requires |
| responsiveSizeSelection | Choose a supported size within available bounds | Enabled unless false | Keep default for responsive layouts |
| bidfloor / bidfloorCurrency | Minimum bid and three-letter currency | Both omitted or both supplied. Nonnegative finite amount. | Saved project or explicit paired override. Not a guaranteed payout. |
| blockedCategories | Category exclusions | Optional. Omit to retain project policy. | Saved policy / stricter supported override |
| onDiagnostic | Fixed diagnostic code callback | Optional, no logger | Publisher. 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 / hook | Value or default | Publisher responsibility |
|---|---|---|
| target | Required HTMLElement | Stable visible container with available width |
| clientId / surfaceId / jobType | Required, matching server | Keep Dashboard values |
| userId / conversationId | Required app identifiers | Use current user/conversation, never credentials |
| turnBinding / sessionId | turnBinding defaults false. Current generated path sets true with trusted sessionId. | Obtain session from authenticated server, rebind on changes |
| timing / consentMode | Low-level defaults during / wavebird_consent | Use saved server values, do not rely on a mismatched default |
| placementEndpoint / consentEndpoint | Low-level defaults /api/sponsor-slot and /api/sponsor-consent | Generated files explicitly use /api/wavebird/placement and /api/wavebird/consent. Match your authenticated routes. |
| rendererUrl | Only https://api.wavebird.ai/v1/render.js | Use default official renderer |
| getFormat | Optional auto, banner, native or clip callback | Restrict to saved allowed formats |
| privacySettingsTarget | Optional selector | Provide 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.request | Existing authenticated model request | Forward supplied headers, input validation and abort signal |
| connectGeneration.consume | Existing stream/output consumer | onDelta 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 / dispose | Explicit lifecycle calls | Rebind on user/conversation changes, dispose on unmount |
| grant / deny / withdraw | Actual user choice only | Use 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.