Consent
Consent is enforced at the API boundary. Script Tag can collect it for you, backend placement requests can carry request-level consent flags, or you can optionally sync session-level consent through /v1/consent. These paths are separate and routing must remain bounded by the active consent state.
Consent model
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.
Decision guide
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. |
Activation boundary
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.
Sync
/v1/consent shape
Canonical sync body
Send client_id, session_id, decision, source: "publisher_custom", and canonical purposes flags such as semantic_targeting, session_persistence, cross_session_persistence, and prompt_shared.
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.
Routing
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 | No |
| Consent sync | /v1/consent | session/user-level CMP or publisher consent state | Optional |
JSON
Canonical /v1/consent sync body
{
"client_id": "wbproj_...",
"session_id": "sess_...",
"decision": "custom",
"source": "publisher_custom",
"purposes": {
"semantic_targeting": false,
"session_persistence": true,
"cross_session_persistence": false,
"prompt_shared": false
}
}Behavior
What the API enforces
TCF-compatible CMP signals and jurisdiction profile
CMP-provided TC strings and jurisdiction hints affect whether relevance, persistence, or disclosure modes are allowed for the active request.
Fail-closed behavior
If consent or config is missing for a stricter profile, the sponsor path can resolve as no-fill while the app itself continues normally.
Prompt sharing is explicit
If prompt.text is sent while prompt_shared is false, raw prompt text is ignored for matching and is not sent to SSPs, DSPs, advertisers, or other ad partners.
Need help with your integration?
Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.