Consent State

CookieBoss persists consent choices in both a first-party cookie and localStorage for maximum reliability.

Storage locations

StorageKeyPurpose
Cookiecookieboss_consentPrimary storage. SameSite=Lax, Secure, 5-year expiry, path=/
localStoragecookieboss_consentFallback if cookies are cleared or blocked

CookieBoss reads from the cookie first, falling back to localStorage. When consent is saved, both are written simultaneously.

ConsentState shape

The stored value is a JSON object:

typescript 
interface ConsentState {
hasConsented: boolean;     // Whether the visitor has made a choice
isExpired: boolean;        // Whether the consent has expired
categories: ConsentCategories;
consentTimestamp: number | null;  // Unix ms when consent was given
scriptVersion: number;     // Script version at time of consent
}

interface ConsentCategories {
necessary: true;     // Always true
analytics: boolean;
marketing: boolean;
functional: boolean;
}

From JavaScript

javascript 
// Using the SDK (recommended)
const categories = window.__cookieboss.getConsent();

// Reading the cookie directly
const raw = document.cookie
.split('; ')
.find(c => c.startsWith('cookieboss_consent='));
if (raw) {
const state = JSON.parse(decodeURIComponent(raw.split('=')[1]));
console.log(state);
}

From the browser console

javascript 
// Quick check
window.__cookieboss.getConsent()

// Full state from cookie
JSON.parse(decodeURIComponent(
document.cookie.match(/cookieboss_consent=([^;]*)/)?.[1] ?? '{}'
))

When a visitor has not yet interacted with the banner:

json 
{
"hasConsented": false,
"isExpired": false,
"categories": {
  "necessary": true,
  "analytics": false,
  "marketing": false,
  "functional": false
},
"consentTimestamp": null,
"scriptVersion": 1
}

All optional categories default to false (denied) until the visitor makes a choice. This is the GDPR-compliant default.

After accepting all

json 
{
"hasConsented": true,
"isExpired": false,
"categories": {
  "necessary": true,
  "analytics": true,
  "marketing": true,
  "functional": true
},
"consentTimestamp": 1708186234567,
"scriptVersion": 3
}

Consent expires after the duration configured in your dashboard (default: 5 years). When consent is expired:

  • isExpired is set to true
  • The banner re-appears on the visitor’s next visit
  • The visitor must give fresh consent

The expiry is calculated from consentTimestamp against consentExpiryMs in your site configuration.

Cookie vs expiry

The cookie itself has a 5-year max-age. The consent expiry configured in your dashboard may be shorter — CookieBoss checks consentTimestamp against the configured expiry on each page load, regardless of the cookie’s browser expiry.

To reset a visitor’s consent (useful for testing), clear both storage locations:

javascript 
// Clear consent
document.cookie = 'cookieboss_consent=; path=/; max-age=0';
localStorage.removeItem('cookieboss_consent');

// Reload to see the banner again
location.reload();