Google tags send a gcd parameter with their requests, for example on GA4 collect hits. It is a 12-character string such as 13l3l3R2l5l1 that packs the page's whole consent state: what was granted or denied, by which command, and how the tag was configured.
ConsentString turns that string back into the effective consent of each type, plus every value stored behind it.
For how Consent Mode decides each value and how the gcd string is built, see Google Consent Mode Internals: Consent Decision Chain and the gcd String.
Not affiliated with or endorsed by Google.
npm install @analytics-debugger/consent-stringShips as ESM and CommonJS with TypeScript types, plus a browser build. No dependencies.
Load the IIFE build with a <script> tag and use the ConsentString global:
<script src="https://cdn.jsdelivr.net/npm/@analytics-debugger/consent-string/dist/consent-string.min.js"></script>
<script>
const consent = ConsentString.decode("13l3l3R2l5l1");
</script>For older browsers such as Internet Explorer 11, use the ES5 build, which has the same API:
<script src="https://cdn.jsdelivr.net/npm/@analytics-debugger/consent-string/dist/consent-string.es5.min.js"></script>| File | Browsers | Minified |
|---|---|---|
dist/consent-string.min.js |
Modern | Yes |
dist/consent-string.js |
Modern | No |
dist/consent-string.es5.min.js |
ES5, including IE11 | Yes |
dist/consent-string.es5.js |
ES5, including IE11 | No |
import * as ConsentString from "@analytics-debugger/consent-string";
const consent = ConsentString.decode("13p3lPR2l5l1");
consent.ad_storage; // "denied"
consent.raw.ad_storage.default; // false
consent.raw.ad_user_data.delegatedTo; // "ad_storage"Full result:
{
"ad_storage": "denied",
"analytics_storage": "granted",
"ad_user_data": "denied",
"ad_personalization": "denied",
"containerScopedDefaults": {},
"flags": {
"isConsentModeActive": true,
"isGlobalPrivacyControlEnabled": false,
"usedContainerScopedDefaults": false
},
"meta": {
"usedDeclare": true,
"usedDefault": true,
"usedImplicit": true,
"usedUpdate": false
},
"raw": {
"gcd": "13p3lPR2l5l1",
"ad_storage": { "implicit": true, "default": false },
"analytics_storage": { "implicit": true },
"ad_user_data": { "delegatedTo": "ad_storage", "implicit": true, "declare": true },
"ad_personalization": { "implicit": false },
"containerScopedDefaults": {},
"flags": { "active": true, "gpc": false, "usedContainerScopedDefaults": false }
}
}Anything not set is undefined. The keys are still there in JavaScript, but JSON.stringify drops them, which is why containerScopedDefaults is {} and flags has no adsSignals in the example above.
ad_storage, analytics_storage, ad_user_data and ad_personalization are each the effective consent: "granted", "denied", or undefined when not set.
How the value is worked out: the first value that is set wins, in this order:
update:gtag('consent', 'update', …)default:gtag('consent', 'default', …)declare: a declare commandimplicit: the value the tag assumed without being told
A delegated type takes the value of the type it's delegated to. In the example above, ad_user_data has its own declare set to granted, but it follows ad_storage, so it is denied. A type delegated to "other" (outside these four) keeps its own value.
The values stored for each type are in raw (see below).
The container's own consent defaults, one per consent type: "granted", "denied", or undefined when not set. Check flags.usedContainerScopedDefaults to see whether the container used them. They are reported only, and are not used to work out the consent values.
The flags stored in the string:
| Field | Meaning |
|---|---|
isConsentModeActive |
Consent mode was active on the page |
isGlobalPrivacyControlEnabled |
Global Privacy Control (GPC) was on in the browser |
adsSignals |
The ads signals setting: "granted", "denied", or undefined when not set |
usedContainerScopedDefaults |
The container set its own consent defaults |
Worked out from the four consent types, not stored in the string:
| Field | Meaning |
|---|---|
usedDeclare, usedDefault, usedImplicit, usedUpdate |
True when at least one consent type has that value set |
What the string stores, before the rules above are applied. Every value is true (granted), false (denied), or undefined when not set.
| Field | Meaning |
|---|---|
gcd |
The string that was decoded |
ad_storage, analytics_storage, ad_user_data, ad_personalization |
The type's stored implicit, declare, default and update values, plus delegatedTo when the type follows another type |
containerScopedDefaults |
The container-scoped default for each type |
flags |
active, gpc, adsSignals and usedContainerScopedDefaults as stored |
ConsentString.decode throws an Error instead of guessing when:
- the input is not a string
- the string is shorter than 12 characters
- the format version (first character) is not
1 - a character is outside the gcd alphabet
try {
ConsentString.decode(input);
} catch (error) {
console.warn("Not a valid gcd string:", error.message);
}The decoder checks the alphabet strictly because of how the bits work: an unknown character would otherwise read as "granted".
All of these are exported:
| Type | Description |
|---|---|
DecodedGcd |
The return value of decode |
ConsentDetails |
One consent type in raw: its stored values and delegatedTo |
ConsentState |
"granted" | "denied" (not set is undefined) |
GcdFlags |
The flags object |
GcdMeta |
The meta object |
GcdRaw |
The raw object |
ConsentType |
"ad_storage" | "analytics_storage" | "ad_user_data" | "ad_personalization" |
The full explanation is in this post. In short:
Each character stores 6 bits, using the alphabet 0-9 a-z A-Z - _. Every consent value takes 2 bits: 1 not set, 2 denied, 3 granted.
| Position | Contents |
|---|---|
| 0 | Format version, currently 1 |
| 1–8 | One pair per type, in the order ad_storage, analytics_storage, ad_user_data, ad_personalization. First character: (delegation << 2) | implicit. Second character: (declare << 4) | (default << 2) | update |
| 9 | Flags: (gpc << 3) | (active << 2) | adsSignals |
| 10 | Container-scoped defaults: (ad_storage << 4) | (analytics_storage << 2) | ad_user_data |
| 11 | (usedContainerScopedDefaults << 2) | ad_personalization |
Delegation codes: 0 not delegated, 8 delegated to another type, 12 + index delegated to the type at that index in the order above.
Every position and bit offset is defined in src/definitions.ts.
npm install
npm test # run the tests
npm run build # build dist/: ESM, CJS, types, and the browser buildsThe builds are configured in vite.config.ts. scripts/build-es5.mjs then compiles the browser build to ES5 with SWC. The build fails if the ES5 output contains newer syntax, relies on functions ES5 doesn't have, or adds any global besides ConsentString. Because of that, the source sticks to plain loops, indexOf and objects instead of Set, find or Object.fromEntries.
The source is four files:
src/definitions.ts: every position, bit field and code in the string, plus the precedence rulesrc/types.ts: the typessrc/helpers.ts: validation, reading characters, bits and fields, following delegation, and working out each statesrc/index.ts: the license, the exports, anddecode
MIT