Cookies and browser storage

The browser runtime keeps the visitor's choice in first-party cookies and in local storage. Their names, formats and lifetimes are listed here, with the functions that parse the cookies.

Requirements#

• Runtime version 1.0.7, loaded with a publishable key.
• To parse the cookies in a bundle: the @piedap/consent npm package.
• To parse them on a server: the Node.js helpers or the Python helpers.

Install#

Load the runtime with the script tag or the npm package. See Browser runtime options.

Import the parsers#

import {
  parseConsentCookie,
  parsePartnerCookie,
  COOKIE_NAME,
  PARTNER_COOKIE_NAME,
} from '@piedap/consent';

COOKIE_NAME is piedap_consent and PARTNER_COOKIE_NAME is piedap_partners.

Cookies#

Each cookie is set with these attributes:

piedap_consent#

Lets your server read the choice on the next request.

1|<consent id>|<form version>|<purposes>|<decided at>

1|cns_3f9a1c0e5b7d4a2c9e8f6b1d0a7c5e42|3|analytics:1~marketing:0|1790577672

The value is percent-encoded in the cookie itself, so document.cookie shows 1%7Ccns_…%7C3%7C…. Decode it before you split it.

piedap_partners#

Lists the partners that are off under a purpose the visitor allowed.

1|<purpose>:<partner>.<partner>~<purpose>:<partner>

1|analytics:matomo.plausible~marketing:meta

A partner that is not listed follows its purpose in piedap_consent. The cookie is removed when no partner is off.

euconsent-v2#

Holds the IAB TC string where IAB TCF applies. See IAB TCF and GPP.

Parse the cookies#

parseConsentCookie()#

Reads a piedap_consent value.

Returns { consentId, formVersion, decisions, decidedAt }, or null. consentId is null while the cookie says pending. decisions maps a purpose key to allowed, and decidedAt is a Date.

Errors None. A missing or malformed cookie returns null.

function cookie(name) {
  const match = document.cookie
    .split('; ')
    .find((part) => part.startsWith(`${name}=`));
  return match ? match.slice(name.length + 1) : null;
}

const consent = parseConsentCookie(cookie(COOKIE_NAME));
console.log(consent?.decisions.analytics); // true

parsePartnerCookie()#

Reads a piedap_partners value.

Returns Record<string, string[]>, purpose key to the partner keys that are off, or null.

Errors None. A missing or malformed cookie returns null.

const declined = parsePartnerCookie(cookie(PARTNER_COOKIE_NAME));
console.log(declined); // { analytics: ['matomo', 'plausible'] }

Local storage#

piedap.consent.v2 has these fields:

Each answer and each withdrawal goes into pending before its request is sent, together with the request itself. It leaves pending when the API has it. A request cut off by the visitor leaving the page is sent again on the next page. It goes with the same body and the same Idempotency-Key, so the API records it once.

Writes for one form are sent one after another, in the order they were made. A write that fails 8 times is dropped.

If local storage is not available, the runtime keeps the state in memory for the page view and relies on the cookie. On a subdomain that shares the cookie but not the storage, it sends the cookie's consent id to the API and adopts the recorded answer.

Cookies removed on refusal#

When a category stops being allowed, the runtime deletes the first-party cookies known to belong to it. The list is your project's cookie declaration plus these names:

The runtime cannot delete third-party cookies. They live on the other party's domain.