# Interface: FidesOptions

FidesJS supports a variety of custom options to modify it's behavior or
enable more advanced usage. For example, the `fides_locale` option can be
provided to override the browser locale. See the properties list below for
the supported options and example usage for each.

Any of the FidesJS options can be provided in one of three ways:

1. **Query Params** (e.g. `example.com?fides_locale=es`): typically used only for testing
2. **Window Object** (e.g. `window.fides_overrides = { fides_locale: "es" }`): typically used to configure FidesJS via an inline `<script>` tag on
the page for customization
3. **Cookie Values** (e.g. `document.cookie="fides_locale=fr-CA"`): typically used
to pass page-specific options from your server to the browser, or from a
native app -> webview, etc.

If the same option is provided in multiple ways, they are evaluated in that
order of precedence:
1. Query Params (top priority)
2. Window Object (second priority)
3. Cookie Values (last priority)

## Example

Configure `window.fides_overrides` before loading Fides.js tag
```html
<head>
  <script>
    // Configure FidesJS options using the window.fides_overrides object
    window.fides_overrides = {
      fides_disable_banner: true,
      fides_embed: true,
      fides_locale: "es",
    };
  </script>
  <script src="path/to/fides.js"></script>
</head>
```
Configure `window.fides_overrides` after loading Fides.js tag
```html
<head>
  <script src="path/to/fides.js">
    // Loading Fides.js before setting window.fides_overrides requires re-initialization
  </script>

  <script>
    function onChange(newData) {
      // Update Fides options
      window.fides_overrides = window.fides_overrides || {};
      window.fides_overrides = {
        fides_locale: newData,
      };

      // Reinitialize FidesJS
      window.Fides.init();
    };
  </script>
</head>
```

## Properties

### fides\_clear\_cookie

> **fides\_clear\_cookie**: `boolean`

When `true`, deletes the `fides_consent` or `fides_consent_suffix` cookie when FidesJS is
initialized, to clear any previously saved consent preferences from the
user's device. This option will only clear the cookie for the matching cookie name suffix or `fides_consent`
if no suffix is provided.

Defaults to `false`.

***

### fides\_disable\_banner

> **fides\_disable\_banner**: `boolean`

When `true`, disable the FidesJS banner from being shown.

Defaults to `false`.

***

### fides\_disable\_save\_api

> **fides\_disable\_save\_api**: `boolean`

When `true`, disable FidesJS from saving user consent preferences to the Fides API.

Defaults to `false`.

***

### fides\_disable\_notices\_served\_api

> **fides\_disable\_notices\_served\_api**: `boolean`

When `true`, only disable FidesJS from saving notices served to the Fides API.

Defaults to `false`.

***

### fides\_external\_id?

> `optional` **fides\_external\_id**: `string`

Provide a custom ID for the current user, to include as an `external_id`
when saving their user consent preferences to the Fides API and the
fides_consent cookie.

This can be used to link a user's consent preferences to a saved profile on
your site, such as a CRM ID, etc.

Empty or whitespace-only values are treated as not set (same as omitting or
undefined), consistent with [Fides.setIdentity](Fides.md#setidentity).

Note that the `fides_user_device_id` is still always generated and included
in the saved user consent preferences, to ensure that per-device
preferences are properly stored for reporting.

Defaults to `undefined`.

#### Examples

Set external ID at init via overrides (e.g. known before Fides loads):
```html
<head>
  <script>
    window.fides_overrides = { fides_external_id: "example-crm-id-123" };
  </script>
  <script src="path/to/fides.js"></script>
</head>
```

Set external ID after init when the user logs in (see [Fides.setIdentity](Fides.md#setidentity)):
```html
<body>
  <script src="path/to/fides.js"></script>
  <script>
    // When your app resolves the logged-in user, set their ID so consent is linked
    function onUserLoggedIn(userId) {
      Fides.setIdentity({ external_id: userId });
    }
  </script>
</body>
```

***

### fides\_embed

> **fides\_embed**: `boolean`

When `true`, require FidesJS to "embed" it's UI into a specific `<div>` on
the page, instead of as an overlay over the `<body>` itself. This is useful
for creating a dedicated page to manage consent preferences on your site.
Both the consent modal and the banner will be embedded into the container.
To only embed the consent modal, set `fides_disable_banner` to `true`.

To use the `fides_embed` option, ensure that a DOM element with
`id="fides-embed-container"` exists on the page, which FidesJS will then
use as the parent element to render within.

NOTE: If you're using a JavaScript framework (e.g. React), ensure that you
do not re-render the parent `<div>` element, as this could remove the
FidesJS UI fully from the page!

Defaults to `false`.

#### Example

```html
<head>
  <script>
    // Configure FidesJS to embed into the page
    window.fides_overrides = {
      fides_embed: true,
    };
  </script>
  <script src="path/to/fides.js"></script>
</head>
<body>
  <div id="fides-embed-container">
    <!-- FidesJS will render it's UI here! -->
  </div>
</body>
```

***

### fides\_locale

> **fides\_locale**: `string`

Override the browser's preferred locale (`navigator.language`) when
selecting the best translations for the FidesJS UI.

Must be set to a `string` that is a valid language code (e.g. `"en-US"`,
`"fr"`, `"zh-CN"`). See https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language

Defaults to `undefined`.

***

### fides\_string

> **fides\_string**: `string`

Override the current user's `fides_string` consent preferences (see [Fides.fides\_string](Fides.md#fides_string)). Can be used to synchronize consent preferences for a
registered user from a custom backend, where the `fides_string` could be
provided by the server across multiple devices, etc.

The string consists of four parts separated by commas in the format:
`TC_STRING,AC_STRING,GPP_STRING,NC_STRING` where:

- TC_STRING: IAB TCF (Transparency & Consent Framework) string
- AC_STRING: Google's Additional Consent string
- GPP_STRING: IAB GPP (Global Privacy Platform) string
- NC_STRING: Base64 encoded string of the user's Notice Consent preferences.

#### Example

Complete string with all parts:
```
"CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA,2~61.70~dv.33,DBABLA~BVAUAAAAAWA.QA,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"
```

TC and AC strings only:
```
"CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA,2~61.70~dv.33"
```

GPP string only:
```
",,DBABLA~BVAUAAAAAWA.QA"
```

Notice Consent string only:
```
",,,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"
```

To properly encode the Notice Consent string, use the
`window.Fides.encodeNoticeConsentString` function (see [Fides.encodeNoticeConsentString](Fides.md#encodenoticeconsentstring)) or write your own function that
looks something like:
```ts
function encodeNoticeConsentString(consent: Record<string, boolean | 0 | 1>) {
  return btoa(JSON.stringify(consent));
}
```

For debugging purposes, you can decode the Notice Consent string using the
`window.Fides.decodeNoticeConsentString` function (see [Fides.decodeNoticeConsentString](Fides.md#decodenoticeconsentstring)).

Note: The Notice Consent string will take precedence over [GPC](/regulations/gpc) and override any prior user consent.

Defaults to `undefined`.

***

### fides\_tcf\_gdpr\_applies

> **fides\_tcf\_gdpr\_applies**: `boolean`

Override the value for `gdprApplies` set in the IAB TCF CMP API.  FidesJS
will always default this value to `true` (since the TCF experience will
typically only be enabled in locations where GDPR applies), but this can be
overriden at the page-level as needed. Only applicable to a TCF experience.

For more details, see the [TCF CMP API technical specification](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#what-does-the-gdprapplies-value-mean)  *

Defaults to `true`.

***

### fides\_consent\_override

> **fides\_consent\_override**: `"accept"` \| `"reject"`

FidesJS will automatically opt in or out of all notices with this option and
only show the consent modal upon user request. This is useful for any
scenario where the user has previously provided consent in a different
context (e.g. a native app, another website, etc.) and you want to ensure
that those preferences are respected.

Defaults to `undefined`.

***

### ot\_fides\_mapping

> **ot\_fides\_mapping**: `string`

Given a OneTrust → Fides notice mapping exists and the OneTrust cookie exists, Fides will "migrate" those consents to Fides privacy notices, and write to the Fides cookie.

This way, Fides customers that are migrating away from OneTrust don't need to show their users new consent dialogues when switching to Fides.
that those preferences are respected.

Example original otFidesMapping data:
{
   'C0001': ['essential_cookies'],
   'C0002': ['analytics_tracking'],
   'C0004': ['advertising', 'targeted_ads']
}

To encode original data to the format expected by this field, use:
encodeURIComponent(JSON.stringify(otFidesMapping))

To decode this field, use:
JSON.parse(decodeURIComponent(ot_fides_mapping))

Field defaults to `undefined`.

***

### transcend\_fides\_mapping

> **transcend\_fides\_mapping**: `string`

Given a Transcend → Fides notice mapping exists and the Transcend cookie exists,
Fides will "migrate" those consents to Fides privacy notices, and write to the Fides cookie.

This way, Fides customers that are migrating away from Transcend don't need to show
their users new consent dialogues when switching to Fides.

Example original transcendFidesMapping data:
{
   'Analytics': ['analytics_tracking'],
   'SaleOfInfo': ['data_sales'],
   'Advertising': ['advertising', 'targeted_ads']
}

To encode original data to the format expected by this field, use:
encodeURIComponent(JSON.stringify(transcendFidesMapping))

To decode this field, use:
JSON.parse(decodeURIComponent(transcend_fides_mapping))

Field defaults to `undefined`.

***

### fides\_consent\_non\_applicable\_flag\_mode

> **fides\_consent\_non\_applicable\_flag\_mode**: `"omit"` \| `"include"`

Define how non-applicable privacy notices are handled.

When set to "include", consent preferences will include notices in the system that are not applicable
to the current experience, and will set the notice as implicitly consented.

When set to "omit" (default), non-applicable notices will be omitted.

Defaults to "omit".

***

### fides\_consent\_flag\_type

> **fides\_consent\_flag\_type**: `"boolean"` \| `"consent_mechanism"`

Define the type of flag to use for consent values.

When set to "boolean", consent preferences will be set as boolean values.
When set to "consent_mechanism", consent preferences will be set as string values based on the
consent mechanism (e.g. "opt-in", "opt-out", "non-applicable").

Defaults to "boolean".

***

### fides\_disabled\_notices

> **fides\_disabled\_notices**: `string`

A comma-separated list of notice_keys to disable their respective Toggle elements in the CMP Overlay.

For example: "data_sales,data_sharing,analytics"

Defaults to `undefined`.

***

### fides\_att\_status

> **fides\_att\_status**: `"denied"` \| `"not_determined"` \| `"restricted"` \| `"authorized"`

Apple ATTrackingManager authorization status, set by the mobile SDK before loading the
embedded TCF consent experience. When `"denied"` or `"restricted"`, custom privacy notices
where `att_exempt` is `false` (or unset) are automatically disabled (toggle locked to
opt_out); notices with `att_exempt: true` remain interactive.

Mirrors Apple's `ATTrackingManager.AuthorizationStatus` enum values:
- `"not_determined"` — user has not yet been asked (default)
- `"restricted"` — tracking is restricted by device policy; notices locked
- `"denied"` — user explicitly denied ATT; notices locked
- `"authorized"` — user granted ATT; no locking applied

Only applies to the TCF embedded consent experience on iOS. Android and web contexts
should not set this option (they default to `"not_determined"`, which applies no locking).

Defaults to `"not_determined"`.

***

### fides\_disabled\_systems?

> `optional` **fides\_disabled\_systems**: `string`

A comma-separated list of systems whose related notice assets (e.g., cookies) should be excluded
from responses. This is used to filter out assets by system name when rendering disclosures.

For example: "google_analytics,facebook_ads"

Defaults to `undefined`.

***

### fides\_initialized\_event\_mode

> **fides\_initialized\_event\_mode**: `"multiple"` \| `"once"` \| `"disable"`

Controls when the deprecated FidesInitialized event should be dispatched.

- "multiple" = fires alongside both FidesReady and FidesConsentLoaded events
- "once" = fires alongside FidesReady only
- "disable" = never fires

Defaults to `"once"`.

***

### fides\_modal\_default\_view?

> `optional` **fides\_modal\_default\_view**: `string`

A URL-like route that determines which view is shown by default when the consent modal is opened.
Currently only affects TCF.

- "/tcf/purposes" ("purposes" tab will be shown if not set)
- "/tcf/features"
- "/tcf/vendors"

Defaults to `undefined`.

***

### fides\_modal\_display?

> `optional` **fides\_modal\_display**: `"immediate"` \| `"default"`

Whether to show the modal immediately on page load.

- "immediate" = skips banner and shows the modal immediately on page load
- "default" = shows the modal when the "manage preferences" link is clicked (default behavior)

***

### fides\_unsupported\_repeated\_script\_loading?

> `optional` **fides\_unsupported\_repeated\_script\_loading**: `"enabled_acknowledge_not_supported"` \| `"disabled"`

Controls handling of unsupported repeated script loading scenarios. When
FidesJS is loaded multiple times on the same page, this setting determines
the behavior.

- "enabled_acknowledge_not_supported" = allows repeated loading but acknowledges
  this is not a supported configuration
- "disabled" = prevents repeated script loading entirely

See [Troubleshooting](/privacy-center-fidesjs/fidesjs/troubleshooting) for more information.

Defaults to `"disabled"`.

***

### fides\_cookie\_suffix?

> `optional` **fides\_cookie\_suffix**: `string`

Adds a suffix to the name of the cookie that Fides uses to store consent preferences.

If provided, the cookie name will be `fides_consent_{suffix}`. For example, if set to
`"mycompany"`, the cookie will be named `fides_consent_mycompany`. This allows multiple
Fides instances on the same domain to maintain separate consent cookies.

Defaults to `undefined`, which uses the standard `fides_consent` cookie name.

***

### fides\_cookie\_compression

> **fides\_cookie\_compression**: `"gzip"` \| `"none"`

Specifies the compression method to use for the consent cookie. When set to "gzip",
compression is always applied regardless of cookie size. This can help reduce cookie
size when storing consent preferences with TCF strings or many vendors.

- "none" = No compression applied (default)
- "gzip" = Always apply gzip compression to the cookie value

Defaults to `"none"`.
