Skip to content

About

Google Consent String Parser

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

ConsentString: gcd decoder for Google Consent Mode

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.

Install

npm install @analytics-debugger/consent-string

Ships as ESM and CommonJS with TypeScript types, plus a browser build. No dependencies.

Browser

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

Usage

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 }
  }
}

The result

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.

One key per consent type

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:

  1. update: gtag('consent', 'update', …)
  2. default: gtag('consent', 'default', …)
  3. declare: a declare command
  4. implicit: 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).

containerScopedDefaults

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.

flags

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

meta

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

raw

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

Errors

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".

Types

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"

How the string is built

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.

Development

npm install
npm test        # run the tests
npm run build   # build dist/: ESM, CJS, types, and the browser builds

The 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 rule
  • src/types.ts: the types
  • src/helpers.ts: validation, reading characters, bits and fields, following delegation, and working out each state
  • src/index.ts: the license, the exports, and decode

License

MIT

About

Google Consent String Parser

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages