airgap.js Load Options Glossary
Configuration load options support by airgap.js
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.
UI & User Experience
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.
autofocus
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.
ui-z-index
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.
message-map
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"}.
message-folder
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.
ui-shadow-root
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.
prompt
Type: "on" | "true" | "off" | "false" | "0"
Overrides the per-regime prompting settings on the banner to either force-on or force-off the banner.
override-locale
Type: string
Forces on a specific locale for your consent UIs. Please ensure this is a BCP 47 string, and that it corresponds to one of the enabled locales for all of your Consent Experiences.
Legacy Consent Banners
These options apply to legacy consent banner implementations. For the latest consent UI, see UI & User Experience above.
airgap
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.
autofocus
Options: "on" | "off"
Default: "on"
Whether to focus on the first descendant of the root arg with the data-initialFocus attribute.
base-url
Type: string
Current page base location override for relative URL resolution.
css
Type: string
Custom path to a CSS file containing the default consent manager UI's stylesheet.
default-log-level
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.
dismissed-view-state
Type: string
The state the consent manager should go to when dismissed.
more-choices-view
Type: string
The view the consent manager should display when "More Choices" button is clicked. Can be either "CompleteOptionsToggles" or "CompleteOptions" (default).
inline-css
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.
lazy-load-ui
Options: "on" | "off"
Default: "off"
Lazy-load the consent manager UI. When enabled, the UI module loads only when UI display APIs are called.
log
Type: string
Default: "error warn"
Enabled log level(s). Available levels: fatal, error, warn, info, log, debug, and trace.
messages
Type: string
Custom path to translation files for the default UI (overrides consentManagerConfig.messages).
privacy-policy
Type: string
Privacy policy URL.
prompt
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.
ui-shadow-root
Type: "open" | "closed"
Default: "closed"
UI shadow root configuration. Set this to "open" to expose the UI shadow root for external inspection and automation.
consent-manager-config
Type: ConsentManagerConfigInput | string
Consent manager UI configuration. Can be a sparse ConsentManagerConfig object or JSON string.
Regulation
auto-reload
Options: "on" | "off"
Default: "on"
Automatically reload the context (init) realm on consent changes that require a modified CSP.
bup
Options: "on" | "off"
Default: "on"
Propagate node baseURI context information in the DOM regulation engine.
cookie-listener-regulation
Options: "on" | "off"
Default: "on" (as of 9.144.0)
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.
csp
Type: string
Default: "allow-known-hosts allow-subdomains"
CSP protection configuration (relevant if Unknown Request Policy is set to block).
default-regime
Type: string
Default: "Unknown"Default privacy/legal regime.
disabled
Options: "true" | "false"
Default: "false"
Disable airgap.js. Set to "true" to disable airgap.js entirely.
disable-when-consented
Options: "on" | "off"
Default: "on"
Disable airgap patcher protections when the user is fully consented to all tracking purposes and there are no registered request or cookie overrides.
dom-protection-cache
Options: "on" | "off"
Default: "on"
DOM protection caching configuration.
load-policies-sync
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.
monitoring
Options: "on" | "off" | "export"
Default: "off"
Monitoring mode.
mutation-observer
Options: "on" | "off"
Default: "off"
Use a MutationObserver regulation fallback while the primary document is still open (loading).
nonce
Type: string
Specify a nonce for satisfying an existing Content Security Policy.
partition
Type: string
Consent partition. If set, consent records are keyed by this partition identifier.
protect
Options: "on" | "off"
Default: "on"DOM protection configuration.
protect-realms
Options: "self" | "descendants" | "*"
Default: "*"
Auto-protect all accessible same-origin realms with airgap.js.
realm-protection-hooks
Type: string
Realm protection same-origin request hooks. Available hooks: nav (default nav:sync), nav:async, and worker.
regime
Type: string
Override for privacy/legal regimes. Individual regimes must be separated by semicolons.
regime-detection
Options: "on" | "off" | "ip-only" | "heuristics-only"
Default: "on"
Regime detection configuration.
regime-precedence
Type: string
Semicolon-separated ordered list of privacy regimes (for multi-regime precedence).
regime-purpose-scopes
Type: string
Regime tracking purpose scoping configuration.
regulate-cookies
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.
regulate-navigation
Options: "on" | "off"
Default: "off"
Regulate transitive top-level (relative to any protected context realms) navigation with airgap.js. Read more: Navigation Control
regulate-requests
Options: "on" | "off"
Default: "on"
Regulate network requests with airgap.js.
report-only
Options: "on" | "off"
Default: "off"
Enable report-only mode.
replay
Type: string | "*" | "off"
Default: "*"
Configuration for replaying quarantined events. Supported tokens: requests, mutations
sync-xhr
Options: "on" | "off"
Default: "on"
Deprecated.
Whether scripts can make synchronous XMLHttpRequests.
tamper-resist
Options: "on" | "off"
Default: "off"
Enable active anti-tamper interventions.
unknown-cookie-policy
Options: "block" | "allow" | "require-full-consent"
Default: "allow"
How to regulate cookies with unknown purposes.
unknown-request-policy
Options: "block" | "allow" | "require-full-consent"
Default: "block" if CSP is enabled; otherwise "allow"
How to regulate network requests with unknown purposes.
quarantine-size
Type: number
Default: 2621000
Event quarantine maximum size (in bytes).
cache-gc-interval
Type: number
Default: 300000
Cache garbage collection interval in milliseconds (0 = disable GC).
cache-key-size
Type: number
Default: 1000
Cache key size limit (in UTF-16 string.length units).
regulation-cache-size
Type: number
Default: 70000
Regulation cache size limit (# of entries). -1 = unbounded, 0 = disabled.
consent-precedence
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.
auto-expire
Type: number
Default: 0
Quarantine pending event auto-expiry time limit (in minutes). 0 = no expiry.
integrations / tracker-overrides
Type: string
Default: "VimeoDNT YouTubePrivacyEnhancedMode WistiaDNT GoogleConsentMode FacebookLDU"
Consent Integrations configuration.
tracker-overrides-unconsented-purpose
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.
Telemetry
event-sample-rate
Type: number
Default: 1
Client-side telemetry event sampling rate (percentage of outgoing requests/cookie mutations to track).
initial-telemetry-sync-period
Type: number
Default: 30
Initial telemetry logging sync period (in seconds).
require-tfpf
Options: "on" | "off"
Default: "off"
Require support for telemetry false positive filtering (TFPF) for event telemetry.
telemetry
Type: TelemetryConfig
Default: "on"
Airgap telemetry toggle.
telemetry-endpoint
Type: string
Telemetry endpoint URL.
telemetry-partitioning
Options: "origin" | "path" | "url"
Default: "origin"
Partition key strategy for telemetry page stats.
telemetry-processing-period
Type: number
Default: 5000
Telemetry processing period (in milliseconds).
telemetry-sample-rate
Type: number
Default: 1
Telemetry sampling rate (percentage of sessions to send telemetry for).
telemetry-sync-period
Type: number
Default: 300
Telemetry sync period (in seconds).
telemetry-tracking-purpose
Type: string
Default: "Functional"
Tracking purpose assigned to the telemetry endpoint.
tfpf
Options: "on" | "off"
Default: "on"
Enable telemetry false positive filtering.
tfpf-stack-limit
Type: number
Default: Error.stackTraceLimit || 8
Number of frames to collect for TFPF in Chromium. May be "Infinity".
tfpf-cache-size
Type: number
Default: 1000
Telemetry false positive filter cache size limit (# of entries). -1 = unbounded, 0 = disabled.
Sync
backend-sync
Type: BackendSyncConfig
Default: "on"
Remote sync configuration.
backend-sync-endpoint
Type: string
Remote sync endpoint URL.
bd-interaction-threshold
Type: number
Default: 600
Bounce debouncer interaction threshold (in milliseconds).
defer-sync
Options: "on" | "off"
Default: "off"
Deferred sync. When "on", sync isn't automatically enqueued.
local-sync
Options: "on" | "off" | "allow-network-observable"
Default: "on"
Whether to run cross-domain sync.
quarantine-sync-budget
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.
site
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.
sites
Type: string
Space-separated list of expected sites, preferably eTLD+1. site takes precedence over this setting.
sync
Type: string
Default: "on"
General sync configuration.
sync-endpoint
Type: string
Sync endpoint URL.
sync-endpoint-map
Type: string
Multi-site sync endpoint mapping (JSON format).
sync-groups
Type: string
Shared XDI host sync groups config (JSON). Maps bundle IDs to first-party sets.
sync-period
Type: number
Default: 1800
Airgap consent sync period (in seconds).
waf
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.
IAB TCF
signed-iab-agreement
Options: "yes" | "no" | "unknown"
Whether the site owner has signed the IAB LSPA agreement.
tcf
Options: "on" | "off"
Default: "off"
Whether to enable the IAB TCF API.
tcf-config
Type: TCFConfigInput | string
TCF configuration, including paths to vendor-list.json, CSS, and messages.
XDI
xdi
Type: string
Custom XDI module location load option (overrides airgap.xdi).
xdi-allowed
Type: string
Space/comma-separated list of allowed XDI hosts.
xdi-commands
Type: string
Comma/space-separated list of enabled XDI commands.
xdi-connect-timeout
Type: number
Default: 30000
XDI connection timeout in milliseconds (0 = no timeout).
xdi-require-https
Options: "on" | "off"
Default: "on"
Require XDI connections to come from secure (HTTPS) origins.
Consent Expiry
consent-expiry
Type: number
Default: 0
Consent expiry time limit (in minutes). 0 = no expiry.
on-consent-expiry
Options: "prompt" | "reset"
Default: "prompt"
Consent expiry behavior.
"prompt"= show the consent manager again"reset"= reset consent entirely