Skip to main content
Introducing packages.sweber.dev
Documentation menuConfiguration

Configuration

All options of ConsentConfig.

OptionTypeDescription
consentVersionstringRequired. Bump it to ask every visitor again, e.g. after adding a service.
categoriesConsentCategoryDefinition[]Required. See below.
purposesConsentPurposeDefinition[]Processing purposes behind the categories. Default: one purpose per category. See Purposes.
servicesConsentService[]Services shown in the preference center and addressable by gates.
policyVersionstringOptional. A changed value also asks again.
storageConsentStorageDefault: cookie in the browser, memory on the server.
languagestringde, de-CH, en, fr, it, es, nl, pl, pt.
mode"opt-in" | "opt-out"Default "opt-in".
region, regionRulesstring, Record<string, { mode }>Choose the mode per region. You supply the region; Permito never geolocates.
initialStateConsentState | nullDecision read on the server.
maxAgeDaysnumberAsk again once a decision is older than this. Works with every storage. See Lifetime, GPC and tabs.
globalPrivacyControlboolean | { categories?, signal? }Honour the GPC browser signal. true declines marketing by default while the visitor has not decided.
syncTabsbooleanDecisions apply in all open tabs of the site at once. Default true with the built-in cookie storage, false with your own storage.
now() => DateClock override for tests.

Categories

interface ConsentCategoryDefinition {
  id: string;            // necessary, preferences, statistics, marketing, security or your own
  name?: LocalizedText;  // built-in text for the known ids
  description?: LocalizedText;
  required?: boolean;    // always granted, cannot be declined
  legalBasis?: string;   // free text for your own documentation, never interpreted
}

Purposes

A purpose is the unit that systems outside the browser act on: the newsletter, ad personalisation, a CRM sync. Each one belongs to a category and has an id that is the same in the browser, in the stored decision and in the webhook.

interface ConsentPurposeDefinition {
  id: string;            // stable, used by your backend
  category: string;      // granting or declining the category sets the purpose
  name?: LocalizedText;
  description?: LocalizedText;
}

Without purposes, every category is one purpose with the category's id. A visitor decides per category in the banner. Your code can narrow a granted category to fewer purposes with manager.setPurposeConsent(id, false): a purpose is granted while its category is granted and the purpose was not declined. Declining a category declines all its purposes, granting it again grants them all again. The built-in banner shows categories, not purposes.

A service can list the purposes it serves (purposes: ["newsletter"]). It runs only while its category and all of these purposes are granted.

Services

interface ConsentService {
  id: string;
  name: string;
  category: string;
  provider?: string;
  purpose?: LocalizedText;
  description?: LocalizedText;
  cookies?: { name: string; duration?: LocalizedText; description?: LocalizedText }[];
  dataRecipients?: string[];
  privacyPolicyUrl?: string;
  requiresConsent?: boolean; // default true; you decide, Permito never does
}

Storage

FactoryNotes
createCookieStorage(options)Default. Cookie permito_consent, SameSite=Lax, Secure on https, Path=/, 180 days. Options: name, domain, path, maxAgeSeconds, sameSite, secure.
createLocalStorage(key)Not readable on the server.
createSessionStorage(key)Decision lasts for the browser session.
createMemoryStorage(initial)Tests and demos.
Your own{ get, set, clear }, sync or async.

Stored decision

interface ConsentState {
  schema: 2;
  version: string;          // consentVersion at the time of the decision
  policyVersion?: string;
  timestamp: string;        // ISO 8601
  categories: Record<string, boolean>;
  purposes: Record<string, boolean>; // effective consent per purpose
  services: Record<string, boolean>; // only individual overrides
  source: "banner" | "preferences" | "api" | "import" | "embed";
  region?: string;
  language?: string;
}