Consent State
CookieBoss persists consent choices in both a first-party cookie and localStorage for maximum reliability.
Storage locations
| Storage | Key | Purpose |
|---|---|---|
| Cookie | cookieboss_consent | Primary storage. SameSite=Lax, Secure, 5-year expiry, path=/ |
| localStorage | cookieboss_consent | Fallback 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:
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;
} Reading consent manually
From 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
// Quick check
window.__cookieboss.getConsent()
// Full state from cookie
JSON.parse(decodeURIComponent(
document.cookie.match(/cookieboss_consent=([^;]*)/)?.[1] ?? '{}'
)) Default state (no consent yet)
When a visitor has not yet interacted with the banner:
{
"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
{
"hasConsented": true,
"isExpired": false,
"categories": {
"necessary": true,
"analytics": true,
"marketing": true,
"functional": true
},
"consentTimestamp": 1708186234567,
"scriptVersion": 3
} Consent expiry
Consent expires after the duration configured in your dashboard (default: 5 years). When consent is expired:
isExpiredis set totrue- 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.
Clearing consent
To reset a visitor’s consent (useful for testing), clear both storage locations:
// Clear consent
document.cookie = 'cookieboss_consent=; path=/; max-age=0';
localStorage.removeItem('cookieboss_consent');
// Reload to see the banner again
location.reload();