Consent
Projects using wavebird_consent require a current stored consent record for the authenticated tenant, client_id, and session_id. Record the actual user decision through /v1/consent before placement; inline flags cannot replace or expand that permission.
Choose the genuine decision source
| Project profile | Decision source and responsibility |
|---|---|
| Own CMP (own_cmp) | Your application owns the actual per-user, per-conversation choice. Synchronize it as publisher_custom through /v1/consent; placement privacy metadata uses wrapper_cmp. Those labels describe the source, not a grant of permission. |
| wavebird dialog (wavebird_consent) | Use the genuine wavebird dialog and synchronize its actual choice as wavebird_dialog. The project requires a current stored record for the authenticated tenant, project and session before placement; inline flags cannot replace it. |
Per-user conversation lifecycle
Bind consent, placement and withdrawal to the same anonymous session for one user conversation. Create fresh state when the user or conversation changes; never reuse a shared demo session or replay a cached grant.
Grant only after an explicit current choice. Denial, withdrawal, expiry or an unavailable consent state keeps the slot hidden, cancels pending sponsor work and prevents late rendering and ad beacons. Purpose flags do not grant lifecycle permission.
Preserve observed Sec-GPC across the browser and backend. A positive signal blocks advertising admission; do not strip the signal, protocol strings or denied permission to make a request succeed.
Keep the primary chat stream available without waiting for consent or an ad. Request sponsorship only at the saved Before, During or After phase. Let the package apply format-specific cleanup when generation ends. After work waits for completion and output presentation. Bound each phase's lifetime and cancel it when the conversation changes or its permission is lost.
Consent appearance
The wavebird dialog uses the first supported language in the visitor's browser preferences. Optional consentLocale on createPublisherAds supplies a fallback, such as de-DE. If neither is supported, the dialog uses English. Omit it or use auto to keep the English fallback.
Supported languages: English, Spanish, German, Japanese, French, Portuguese, Russian, Italian, Dutch, Polish, Turkish, Indonesian, Chinese, Persian, Czech, Vietnamese, Korean, Arabic, Ukrainian and Hungarian. Chinese supports simplified and traditional script. Korean uses South Korean wording. Arabic and Persian use right-to-left text.
Optional consentTheme fields are accentColor, backgroundColor and textColor (six-digit hex), fontFamily (existing font names), radius (0 to 20) and spacing (12 to 32). Low-contrast colors use readable fallbacks. No fonts are downloaded.
These options change appearance only. Keep all consent actions visible and usable. Own CMP decisions and server consent requirements remain unchanged.
Three separate controls
Lifecycle consent
A current authoritative consent record permits the placement and renderer lifecycle. If it is refused, expired, or revoked, wavebird does not render or send beacons.
Semantic targeting
semantic_targeting: false disables prompt-derived targeting. Permitted product or placement context is a separate input. Turning semantic targeting off does not remove lifecycle consent requirements.
Prompt sharing
prompt_shared: false keeps raw prompts and chat content out of targeting. Prefer a controlled topic and never send identities.
Which fallback is permitted?
| State | Permitted ad behavior |
|---|---|
| Required lifecycle permission is missing, refused, expired, or revoked | Do not render or send ad beacons. Keep the AI task available; non-personalized delivery is not a way around this requirement. |
| Current lifecycle permission; semantic_targeting is false | Do not derive targeting from the user's prompt. Non-personalized delivery may use permitted product or placement context only when the active jurisdiction, project, and partner rules allow it. |
| prompt_shared is false | Do not use raw prompt text for matching, even if semantic_targeting is enabled. Keep the request within the remaining permitted fields. |
| Both semantic_targeting and prompt_shared are true | Permitted prompt classification can run inside wavebird. Reduce it to allowed semantic fields; raw prompts and chat history still do not reach advertising partners. |
Test data and real-user traffic
Synthetic Test traffic
Server Test Keys can be created before a DPA is signed. Until then, use only synthetic sessions and test data that do not represent real end users.
Real-user testing
A Test integration that sends real end-user data is not treated as synthetic. Complete the DPA first when wavebird acts as processor, and apply the required notice, legal-basis, and consent controls.
Live Ads
Live Ads require a current DPA for every publisher app. Company country prepares the legal workflow, while request-level jurisdiction and CMP signals control the active end-user delivery decision.
/v1/consent shape
Canonical sync body
Use the selected project's complete backend and frontend lifecycle handlers. Include client_id, the same session_id, the actual lifecycle_state, a positive increasing revision, the profile's genuine decision source and canonical purposes. Verify the returned authoritative snapshot before rendering; source labels and inline flags cannot manufacture a user's decision.
Compatibility aliases
The API accepts legacy source: "publisher" and source: "custom_dialog" as publisher_custom. purposes.ads maps to semantic_targeting, purposes.measurement maps to session_persistence, and missing decision is inferred as custom when purposes is supplied.
Response normalization
Successful sync responses include a safe normalized object with canonical source and purposes values so test harnesses can verify alias handling without reading stored server state.
Choose where to pass consent
| Consent path | Location | Purpose | Separate sync needed? |
|---|---|---|---|
| Built-in Script Tag flow | Configured browser dialog | Collect and store permission before the next request | Handled by the tag |
| Request-level placement consent | inside /v1/placements | per-request privacy and targeting signal | Does not replace required stored consent |
| Consent sync | /v1/consent | session-level publisher consent state | Required for wavebird_consent projects |
Use the current lifecycle handlers
Copy the project-scoped ENV, BACKEND and FRONTEND blocks together. The BACKEND block includes both placement and consent routes; never omit the lifecycle handler or substitute a static granted JSON body.
Open the integration guide →Full consent endpoint reference →
What the API enforces
External protocol admission
TCF and GPP inputs are currently rejected at admission with validation_error (400), including structurally valid strings, because an authoritative vendor, purpose, and jurisdiction policy mapping is not configured. Do not interpret field support as permission to deliver ads.
Fail-closed behavior
Admission can return a 403 consent error rather than a successful no-fill response. An observed positive Sec-GPC signal blocks new advertising admission with privacy_signal_policy_required (403). Preserve the signal across backend requests and keep the primary application flow available; do not retry by removing the signal.
Prompt sharing is explicit
Supplying prompt text transmits it to the wavebird API. prompt_shared: false blocks its use for targeting. Standard SSP builders project permitted signal fields rather than forwarding the raw prompt body; separate model requests, custom adapters and application logs require their own review.
Need help with your integration?
Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.