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.
Collection
Supported paths
Built-in Script Tag flow
Recommended browser path. The tag can collect and store consent before the next job creation attempt.
Custom CMP
Use your own CMP or publisher UI and then store the resulting session-level consent state through /v1/consent.
Server-side handling
Backend integrations can carry request-level consent flags directly on /v1/placements: semantic_targeting, prompt_shared, gdpr_applies, and consent_source. In that case, a prior /v1/consent sync is not required.
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 means context-only, non-personalized matching. It does not mean lifecycle consent is missing.
Prompt sharing
prompt_shared: false keeps raw prompts and chat content out of targeting. Prefer a controlled topic and never send identities.
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 beta or 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.
Placement consent remains separate
Request-level placement consent is sent inside /v1/placements and is best for per-request targeting and privacy controls. It works without a prior /v1/consent call.
Routing
Consent path comparison
| Consent path | Location | Purpose | Required before placement |
|---|---|---|---|
| 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
}
}Compatibility remains accepted for older integrations: source: "publisher" normalizes to publisher_custom, purposes.ads maps to semantic_targeting, and purposes.measurement maps to session_persistence.
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 rollout review?
Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.