🍪 Cookie Preferences
Response schema and TCF mapping for stored cookie consent choices
Users set cookie consent choices in Upod. Each toggle maps to a TCF v2.2 purpose (see the mapping table below).
Cookie preferences do not require a separate data-access grant in the user's vault. If the user is logged in on your site, you can fetch them. There is no per-client consent step for this data type.
For a step-by-step integration guide, including CMP adapters, see Handling users' cookie consent.
API methods
| Method | Description |
|---|---|
client.getConsent() | Returns normalized booleans, or null when not logged in or preferences are not set. |
client.onConsentChange(callback) | Fires on login, logout, tab focus, visibility return, and vault edits. |
client.emitConsentChange() | Manually refetch and notify listeners. |
client.fetch({ path: '/storage/cookies', method: 'get' }) | Returns raw DPV strings. No purpose query parameter required. |
Also listens for the upod:consentchange DOM event.
TCF v2.2 mapping
Each toggle the user can change maps to one or more TCF purposes. The API returns each stored toggle as "dpv#consentgiven" or "dpv#consentnotgiven". Essential is the one exception: it is always on and is not included in the response.
| Upod toggle | API field | TCF v2.2 purposes | Legal basis | Default |
|---|---|---|---|---|
| Essential (always on) | (none) | Special Purpose 1: Ensure security, prevent fraud, debug | Legitimate interest / legal obligation | Always on |
| Cookies and similar | cookiesAndSimilar | Purpose 1: Store and/or access information on a device | Consent | Off |
| Advertising | advertising | Purpose 3: Create profiles for personalised advertising Purpose 4: Use profiles to select personalised advertising | Consent (no LI allowed) | Off |
| Personalised content | personalisedContent | Purpose 5: Create profiles to personalise content Purpose 6: Use profiles to select personalised content | Consent (no LI allowed) | Off |
| Measurement | measurement | Purpose 7: Measure advertising performance Purpose 8: Measure content performance Purpose 9: Understand audiences through statistics or market research | Consent or legitimate interest | Off |
| Social media | socialMedia | (site-specific integrations, e.g. embedded sharing buttons) | Consent | Off |
| Other | other | Purpose 2: Use limited data to select advertising Purpose 10: Develop and improve services Purpose 11: Use limited data to select content | Consent or legitimate interest | Off |
Treat Essential as always enabled in your integration. The fields
returned by /storage/cookies are the toggles the user can actually change.
Response format
client.getConsent() returns booleans:
type NormalizedConsent = {
cookiesAndSimilar: boolean;
advertising: boolean;
personalisedContent: boolean;
measurement: boolean;
socialMedia: boolean;
other: boolean;
};The raw /storage/cookies endpoint returns DPV strings instead:
type ConsentValue = 'dpv#consentgiven' | 'dpv#consentnotgiven';
type CookiePreferencesResponse = {
cookiesAndSimilar: ConsentValue;
advertising: ConsentValue;
personalisedContent: ConsentValue;
measurement: ConsentValue;
socialMedia: ConsentValue;
other: ConsentValue;
};If the user has not opted in to a category, the value is false (or "dpv#consentnotgiven" in the raw response). That matches the Off default in the table above.
Example API response (JSON)
{
"cookiesAndSimilar": "dpv#consentgiven",
"advertising": "dpv#consentnotgiven",
"personalisedContent": "dpv#consentgiven",
"measurement": "dpv#consentnotgiven",
"socialMedia": "dpv#consentnotgiven",
"other": "dpv#consentnotgiven"
}Related documentation
- Handling users' cookie consent: fetch preferences and sync to CMP adapters
- API Reference:
client.getConsent(),client.fetch(), and purpose values for profile data - Anonymized profile data: profile data that does require vault consent