airgap.js Load Options Glossary
Overview
Below are the configuration load options supported by airgap.js, expressed in kebab-case for data- attributes.
When defining options via our pre-init config API (e.g., airgap.loadOptions in code), convert from kebab-case to camelCase.
The UI & User Experience options apply to the latest consent experiences (v2). If you are using a legacy consent banner, refer to the Legacy Consent Banners section instead. Some option names overlap between sections but may have different accepted values or behavior.
Options: "on" | "off" | string
Default: "on"
Controls autofocus behavior when the consent UI opens. "on" focuses the first descendant element with the data-initialFocus attribute. "off" disables autofocus entirely. Alternatively, pass a DOM element ID string to focus a specific element directly.
Options: number
The CSS z-index applied to the consent manager UI container. Increase this value if other elements on the page are rendering on top of the consent UI.
Options: string
A map of locale codes to absolute URLs pointing to their respective translation files. When defined, this takes precedence over message-folder for loading localized messages. Example: {"en": "https://example.com/messages/en.json", "fr": "https://example.com/messages/fr.json"}.
Options: string
Base URL of the folder containing localized message files for the consent UI. When message-map is not defined, airgap.js will fetch translations from {messageFolder}/{localeKey}.json. Overridden by message-map if both are set.
Options: "open" | "closed" | "none"
Default: "closed"
Controls the shadow DOM encapsulation mode for the consent manager UI. "closed" encapsulates the UI shadow root from external access. "open" exposes the shadow root for external inspection and automation (e.g., testing). "none" disables shadow root entirely, rendering the UI directly into the main document.
These options apply to legacy consent banner implementations. For the latest consent UI, see UI & User Experience above.
Type: string
Location of the airgap.js bundle. Used for resolving relative paths for other loaded modules, such as the UI module and XDI module.
Options: "on" | "off"
Default: "on"
Whether to focus on the first descendant of the root arg with the data-initialFocus attribute.
Type: string
Current page base location override for relative URL resolution.
Type: string
Custom path to a CSS file containing the default consent manager UI's stylesheet.
Since it can be one of several literal values (info, warn, debug, error, or trace), we treat these as options.
Options: "info" | "warn" | "debug" | "error" | "trace"
Default: "info"Default output log level for logger.log.
Type: string
The state the consent manager should go to when dismissed.
Type: string
The view the consent manager should display when "More Choices" button is clicked. Can be either "CompleteOptionsToggles" or "CompleteOptions" (default).
Options: "on" | "off" | "data:"
Default: "on"
Inline CSS options for the consent management UI. "off" disables CSS, and "data:" injects the CSS using a data: URI in an external <link rel="stylesheet"> tag.
Options: "on" | "off"
Default: "off"
Lazy-load the consent manager UI. When enabled, the UI module loads only when UI display APIs are called.
Type: string
Default language selection for the default UI. Set to undefined to auto-select.
Type: string
Default: "error warn"
Enabled log level(s). Available levels: fatal, error, warn, info, log, debug, and trace.
Type: string
Custom path to translation files for the default UI (overrides consentManagerConfig.messages).
Type: string
Privacy policy URL.
Type: number | "off"
Default: "off"
Automatically prompt user with consent manager UI at n pageviews.
0or"off"= disabled1= prompt on the first pageview2= prompt on the second pageview, etc.
Type: "open" | "closed"
Default: "closed"
UI shadow root configuration. Set this to "open" to expose the UI shadow root for external inspection and automation.
Type: ConsentManagerConfigInput | string
Consent manager UI configuration. Can be a sparse ConsentManagerConfig object or JSON string.
Options: "on" | "off"
Default: "on"
Automatically reload the context (init) realm on consent changes that require a modified CSP.
Options: "on" | "off"
Default: "on"
Propagate node baseURI context information in the DOM regulation engine.
Options: "on" | "off"
Default: "off"
Use CookieStore change event listener to reactively clear server-originated cookies. Note: Setting this option to "on" requires and enables event monitoring (which is required for cookie listener regulation to work), unless monitoring is explicitly disabled.
Type: string
Default: "allow-known-hosts allow-subdomains"
CSP protection configuration (relevant if Unknown Request Policy is set to block).
Type: string
Default: "Unknown"Default privacy/legal regime.
Options: "true" | "false"
Default: "false"
Disable airgap.js. Set to "true" to disable airgap.js entirely.
Options: "on" | "off"
Default: "on"
Disable airgap patcher protections when the user is fully consented to all tracking purposes.
Options: "on" | "off"
Default: "on"
DOM protection caching configuration.
Options: "on" | "off"
Default: "off"
Load policies bundles synchronously. Warning: This option is very bad for performance. It should only be used if you can't rely on quarantine smart replay to smooth out policy changes.
Options: "on" | "off" | "export"
Default: "off"
Monitoring mode.
Options: "on" | "off"
Default: "off"
Use a MutationObserver regulation fallback while the primary document is still open (loading).
Type: string
Specify a nonce for satisfying an existing Content Security Policy.
Type: string
Consent partition. If set, consent records are keyed by this partition identifier.
Options: "on" | "off"
Default: "on"DOM protection configuration.
Options: "self" | "descendants" | "*"
Default: "*"
Auto-protect all accessible same-origin realms with airgap.js.
Type: string
Realm protection same-origin request hooks. Available hooks: nav (default nav:sync), nav:async, and worker.
Type: string
Override for privacy/legal regimes. Individual regimes must be separated by semicolons.
Options: "on" | "off" | "ip-only" | "heuristics-only"
Default: "on"
Regime detection configuration.
Type: string
Semicolon-separated ordered list of privacy regimes (for multi-regime precedence).
Type: string
Regime tracking purpose scoping configuration.
Options: "on" | "off" | "2"
Default: "on"
Regulate cookies with airgap.js. Set to "2" to match cookie RegExp rules against cookie values in addition to the cookie name. i.e. RegExp rules will match against cookie-name=cookie-value instead of just cookie-name.
Options: "on" | "off"
Default: "off"
Regulate transitive top-level (relative to any protected context realms) navigation with airgap.js.
Options: "on" | "off"
Default: "on"
Regulate network requests with airgap.js.
Options: "on" | "off"
Default: "off"
Enable report-only mode.
Type: string | "*" | "off"
Default: "*"
Configuration for replaying quarantined events. Supported tokens: requests, mutations
Options: "on" | "off"
Default: "on"
Deprecated.
Whether scripts can make synchronous XMLHttpRequests.
Options: "on" | "off"
Default: "off"
Enable active anti-tamper interventions.
Options: "block" | "allow" | "require-full-consent"
Default: "allow"
How to regulate cookies with unknown purposes.
Options: "block" | "allow" | "require-full-consent"
Default: "block" if CSP is enabled; otherwise "allow"
How to regulate network requests with unknown purposes.
Type: number
Default: 2621000
Event quarantine maximum size (in bytes).
Type: number
Default: 300000
Cache garbage collection interval in milliseconds (0 = disable GC).
Type: number
Default: 1000
Cache key size limit (in UTF-16 string.length units).
Type: number
Default: 70000
Regulation cache size limit (# of entries). -1 = unbounded, 0 = disabled.
Options: "user" | "signals"
Default: "user"
Consent resolution precedence strategy. Set to 'signals' to disallow user choice from overriding conflicting browser privacy preference signals during consent changes and resolution.
Type: number
Default: 0
Quarantine pending event auto-expiry time limit (in minutes). 0 = no expiry.
Type: string
Default: "VimeoDNT YouTubePrivacyEnhancedMode WistiaDNT GoogleConsentMode FacebookLDU"
Consent Integrations configuration.
Type: string
Default: "SaleOfInfo"
Default trigger tracking purpose for enabling built-in tracker overrides. When this purpose is respected and user has lack of consent then tracker overrides are enabled.
Type: number
Default: 1
Client-side telemetry event sampling rate (percentage of outgoing requests/cookie mutations to track).
Type: number
Default: 30
Initial telemetry logging sync period (in seconds).
Options: "on" | "off"
Default: "off"
Require support for telemetry false positive filtering (TFPF) for event telemetry.
Type: TelemetryConfig
Default: "on"
Airgap telemetry toggle.
Type: string
Telemetry endpoint URL.
Options: "origin" | "path" | "url"
Default: "origin"
Partition key strategy for telemetry page stats.
Type: number
Default: 5000
Telemetry processing period (in milliseconds).
Type: number
Default: 1
Telemetry sampling rate (percentage of sessions to send telemetry for).
Type: number
Default: 300
Telemetry sync period (in seconds).
Type: string
Default: "Functional"
Tracking purpose assigned to the telemetry endpoint.
Options: "on" | "off"
Default: "on"
Enable telemetry false positive filtering.
Type: number
Default: Error.stackTraceLimit || 8
Number of frames to collect for TFPF in Chromium. May be "Infinity".
Type: number
Default: 1000
Telemetry false positive filter cache size limit (# of entries). -1 = unbounded, 0 = disabled.
Type: BackendSyncConfig
Default: "on"
Remote sync configuration.
Type: string
Remote sync endpoint URL.
Type: number
Default: 600
Bounce debouncer interaction threshold (in milliseconds).
Options: "on" | "off"
Default: "off"
Deferred sync. When "on", sync isn't automatically enqueued.
Options: "on" | "off" | "allow-network-observable"
Default: "on"
Whether to run cross-domain sync.
Type: number
Default: 0
Quarantine sync budget (in bytes). 0 = disabled, -1 = unlimited. Note: Best set to the same value as quarantine-size when enabling, which has a default of 2621000.
Type: string
Sync domain scope (for cookie-based consent sync). Set this to the highest level domain within a site that you wish to sync across.
Type: string
Space-separated list of expected sites, preferably eTLD+1. site takes precedence over this setting.
Type: string
Default: "on"
General sync configuration.
Type: string
Sync endpoint URL.
Type: string
Multi-site sync endpoint mapping (JSON format).
Type: string
Shared XDI host sync groups config (JSON). Maps bundle IDs to first-party sets.
Type: number
Default: 1800
Airgap consent sync period (in seconds).
Options: "b64" | "esc"
Set waf=b64 to base64-encode sync cookies or waf=esc to escape sync cookies with URL-safe-encoding. There are no integrated consent migrations for these options at this time, so there is potential for consent loss/reset if this option changes between page visits.
Options: "yes" | "no" | "unknown"
Whether the site owner has signed the IAB LSPA agreement.
Options: "on" | "off"
Default: "off"
Whether to enable the IAB TCF API.
Type: TCFConfigInput | string
TCF configuration, including paths to vendor-list.json, CSS, and messages.
Type: string
Custom XDI module location load option (overrides airgap.xdi).
Type: string
Space/comma-separated list of allowed XDI hosts.
Type: string
Comma/space-separated list of enabled XDI commands.
Type: number
Default: 30000
XDI connection timeout in milliseconds (0 = no timeout).
Options: "on" | "off"
Default: "on"
Require XDI connections to come from secure (HTTPS) origins.
Type: number
Default: 0
Consent expiry time limit (in minutes). 0 = no expiry.
Options: "prompt" | "reset"
Default: "prompt"
Consent expiry behavior.
"prompt"= show the consent manager again"reset"= reset consent entirely