# airgap.js Load Options Glossary (/docs/consent-management/reference/airgap/load-options)

## Overview [#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  [#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**](../../../index.mdx) section instead. Some option names overlap between sections but may have different accepted values or behavior.

#### `autofocus` [#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` [#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` [#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` [#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` [#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` [#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` [#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 [#legacy-consent-banners]

These options apply to legacy consent banner implementations. For the latest consent UI, see UI & User Experience above.

#### `airgap` [#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` [#autofocus-1]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Whether to focus on the first descendant of the root arg with the `data-initialFocus` attribute.

#### `base-url` [#base-url]

**Type:** `string`

Current page base location override for relative URL resolution.

#### `css` [#css]

**Type:** `string`

Custom path to a CSS file containing the default consent manager UI's stylesheet.

#### `default-log-level` [#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` [#dismissed-view-state]

**Type:** `string`

The state the consent manager should go to when dismissed.

#### `more-choices-view` [#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` [#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` [#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` [#log]

**Type:** `string`
**Default:** `"error warn"`

Enabled log level(s). Available levels: `fatal`, `error`, `warn`, `info`, `log`, `debug`, and `trace`.

#### `messages` [#messages]

**Type:** `string`

Custom path to translation files for the default UI (overrides `consentManagerConfig.messages`).

#### `privacy-policy` [#privacy-policy]

**Type:** `string`

Privacy policy URL.

#### `prompt` [#prompt-1]

**Type:** `number` | `"off"`

**Default:** `"off"`

Automatically prompt user with consent manager UI at _n_ pageviews.

- `0` or `"off"` = disabled
- `1` = prompt on the first pageview
- `2` = prompt on the second pageview, etc.

#### `ui-shadow-root` [#ui-shadow-root-1]

**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` [#consent-manager-config]

**Type:** `ConsentManagerConfigInput` | `string`

Consent manager UI configuration. Can be a sparse `ConsentManagerConfig` object or JSON string.

### Regulation [#regulation]

#### `auto-reload` [#auto-reload]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Automatically reload the context (init) realm on consent changes that require a modified CSP.

#### `bup` [#bup]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Propagate node baseURI context information in the DOM regulation engine.

#### `cookie-listener-regulation` [#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](#monitoring) (which is required for cookie listener regulation to work), unless monitoring is explicitly disabled.

#### `csp` [#csp]

**Type:** `string`

**Default:** `"allow-known-hosts allow-subdomains"`

CSP protection configuration (relevant if Unknown Request Policy is set to block).

#### `default-regime` [#default-regime]

**Type:** `string`

**Default:** `"Unknown"`Default privacy/legal regime.

#### `disabled` [#disabled]

**Options:** `"true"` | `"false"`

**Default:** `"false"`

Disable airgap.js. Set to `"true"` to disable airgap.js entirely.

#### `disable-when-consented` [#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` [#dom-protection-cache]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

DOM protection caching configuration.

#### `load-policies-sync` [#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` [#monitoring]

**Options:** `"on"` | `"off"` | `"export"`

**Default:** `"off"`

Monitoring mode.

#### `mutation-observer` [#mutation-observer]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Use a `MutationObserver` regulation fallback while the primary document is still open (loading).

#### `nonce` [#nonce]

**Type:** `string`

Specify a nonce for satisfying an existing Content Security Policy.

#### `partition` [#partition]

**Type:** `string`

Consent partition. If set, consent records are keyed by this partition identifier.

#### `protect` [#protect]

**Options:** `"on"` | `"off"`

**Default:** `"on"`DOM protection configuration.

#### `protect-realms` [#protect-realms]

**Options:** `"self"` | `"descendants"` | `"*"`

**Default:** `"*"`

Auto-protect all accessible same-origin realms with airgap.js.

#### `realm-protection-hooks` [#realm-protection-hooks]

**Type:** `string`

Realm protection same-origin request hooks. Available hooks: `nav` (default `nav:sync`), `nav:async`, and `worker`.

#### `regime` [#regime]

**Type:** `string`

Override for privacy/legal regimes. Individual regimes must be separated by semicolons.

#### `regime-detection` [#regime-detection]

**Options:** `"on"` | `"off"` | `"ip-only"` | `"heuristics-only"`

**Default:** `"on"`

Regime detection configuration.

#### `regime-precedence` [#regime-precedence]

**Type:** `string`

Semicolon-separated ordered list of privacy regimes (for multi-regime precedence).

#### `regime-purpose-scopes` [#regime-purpose-scopes]

**Type:** `string`

Regime tracking purpose scoping configuration.

#### `regulate-cookies` [#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` [#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](../navigation-control.mdx)

#### `regulate-requests` [#regulate-requests]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Regulate network requests with airgap.js.

#### `report-only` [#report-only]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Enable report-only mode.

#### `replay` [#replay]

**Type:** `string` | `"*"` | `"off"`

**Default:** `"*"`

Configuration for replaying quarantined events. Supported tokens: requests, mutations

#### `sync-xhr` [#sync-xhr]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

**Deprecated.**&#x20;

Whether scripts can make synchronous XMLHttpRequests.

#### `tamper-resist` [#tamper-resist]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Enable active anti-tamper interventions.

#### `unknown-cookie-policy` [#unknown-cookie-policy]

**Options:** `"block"` | `"allow"` | `"require-full-consent"`

**Default:** `"allow"`

How to regulate cookies with unknown purposes.

#### `unknown-request-policy` [#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` [#quarantine-size]

**Type:** `number`

**Default:** `2621000`

Event quarantine maximum size (in bytes).

#### `cache-gc-interval` [#cache-gc-interval]

**Type:** `number`

**Default:** `300000`

Cache garbage collection interval in milliseconds (0 = disable GC).

#### `cache-key-size` [#cache-key-size]

**Type:** `number`

**Default:** `1000`

Cache key size limit (in UTF-16 `string.length` units).

#### `regulation-cache-size` [#regulation-cache-size]

**Type:** `number`

**Default:** `70000`

Regulation cache size limit (# of entries). `-1` = unbounded, `0` = disabled.

#### `consent-precedence` [#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` [#auto-expire]

**Type:** `number`

**Default:** `0`

Quarantine pending event auto-expiry time limit (in minutes). `0` = no expiry.

#### `integrations` / `tracker-overrides` [#integrations--tracker-overrides]

**Type:** `string`

**Default:** `"VimeoDNT YouTubePrivacyEnhancedMode WistiaDNT GoogleConsentMode FacebookLDU"`

[Consent Integrations](../../configuration/consent-integrations/consent-built-in-integrations.mdx) configuration.

#### `tracker-overrides-unconsented-purpose` [#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 [#telemetry]

#### `event-sample-rate` [#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` [#initial-telemetry-sync-period]

**Type:** `number`

**Default:** `30`

Initial telemetry logging sync period (in seconds).

#### `require-tfpf` [#require-tfpf]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Require support for telemetry false positive filtering (TFPF) for event telemetry.

#### `telemetry` [#telemetry-1]

**Type:** `TelemetryConfig`

**Default:** `"on"`

Airgap telemetry toggle.

#### `telemetry-endpoint` [#telemetry-endpoint]

**Type:** `string`

Telemetry endpoint URL.

#### `telemetry-partitioning` [#telemetry-partitioning]

**Options:** `"origin" | "path" | "url"`

**Default:** `"origin"`

Partition key strategy for telemetry page stats.

#### `telemetry-processing-period` [#telemetry-processing-period]

**Type:** `number`

**Default:** `5000`

Telemetry processing period (in milliseconds).

#### `telemetry-sample-rate` [#telemetry-sample-rate]

**Type:** `number`

**Default:** `1`

Telemetry sampling rate (percentage of sessions to send telemetry for).

#### `telemetry-sync-period` [#telemetry-sync-period]

**Type:** `number`

**Default:** `300`

Telemetry sync period (in seconds).

#### `telemetry-tracking-purpose` [#telemetry-tracking-purpose]

**Type:** `string`

**Default:** `"Functional"`

Tracking purpose assigned to the telemetry endpoint.

#### `tfpf` [#tfpf]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Enable telemetry false positive filtering.

#### `tfpf-stack-limit` [#tfpf-stack-limit]

**Type:** `number`

**Default:** `Error.stackTraceLimit || 8`

Number of frames to collect for TFPF in Chromium. May be `"Infinity"`.

#### `tfpf-cache-size` [#tfpf-cache-size]

**Type:** `number`

**Default:** `1000`

Telemetry false positive filter cache size limit (# of entries). `-1` = unbounded, `0` = disabled.

### Sync [#sync]

#### `backend-sync` [#backend-sync]

**Type:** `BackendSyncConfig`

**Default:** `"on"`

Remote sync configuration.

#### `backend-sync-endpoint` [#backend-sync-endpoint]

**Type:** `string`

Remote sync endpoint URL.

#### `bd-interaction-threshold` [#bd-interaction-threshold]

**Type:** `number`

**Default:** `600`

Bounce debouncer interaction threshold (in milliseconds).

#### `defer-sync` [#defer-sync]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Deferred sync. When `"on"`, sync isn't automatically enqueued.

#### `local-sync` [#local-sync]

**Options:** `"on"` | `"off"` | `"allow-network-observable"`

**Default:** `"on"`

Whether to run cross-domain sync.

#### `quarantine-sync-budget` [#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` [#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` [#sites]

**Type:** `string`

Space-separated list of expected sites, preferably eTLD+1. `site` takes precedence over this setting.

#### `sync` [#sync-1]

**Type:** `string`

**Default:** `"on"`

General sync configuration.

#### `sync-endpoint` [#sync-endpoint]

**Type:** `string`

Sync endpoint URL.

#### `sync-endpoint-map` [#sync-endpoint-map]

**Type:** `string`

Multi-site sync endpoint mapping (JSON format).

#### `sync-groups` [#sync-groups]

**Type:** `string`

Shared XDI host sync groups config (JSON). Maps bundle IDs to first-party sets.

#### `sync-period` [#sync-period]

**Type:** `number`

**Default:** `1800`

Airgap consent sync period (in seconds).

#### `waf` [#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 [#iab-tcf]

#### `signed-iab-agreement` [#signed-iab-agreement]

**Options:** `"yes"` | `"no"` | `"unknown"`

Whether the site owner has signed the IAB LSPA agreement.

#### `tcf` [#tcf]

**Options:** `"on"` | `"off"`

**Default:** `"off"`

Whether to enable the IAB TCF API.

#### `tcf-config` [#tcf-config]

**Type:** `TCFConfigInput` | `string`

TCF configuration, including paths to `vendor-list.json`, CSS, and messages.

### XDI [#xdi]

#### `xdi` [#xdi-1]

**Type:** `string`

Custom XDI module location load option (overrides `airgap.xdi`).

#### `xdi-allowed` [#xdi-allowed]

**Type:** `string`

Space/comma-separated list of allowed XDI hosts.

#### `xdi-commands` [#xdi-commands]

**Type:** `string`

Comma/space-separated list of enabled XDI commands.

#### `xdi-connect-timeout` [#xdi-connect-timeout]

**Type:** `number`

**Default:** `30000`

XDI connection timeout in milliseconds (`0` = no timeout).

#### `xdi-require-https` [#xdi-require-https]

**Options:** `"on"` | `"off"`

**Default:** `"on"`

Require XDI connections to come from secure (HTTPS) origins.

### Consent Expiry [#consent-expiry]

#### `consent-expiry` [#consent-expiry-1]

**Type:** `number`

**Default:** `0`

Consent expiry time limit (in minutes). `0` = no expiry.

#### `on-consent-expiry` [#on-consent-expiry]

**Options:** `"prompt"` | `"reset"`

**Default:** `"prompt"`

Consent expiry behavior.

- `"prompt"` = show the consent manager again
- `"reset"` = reset consent entirely