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:

Query Params (e.g. example.com?fides_locale=es): typically used only for testing
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
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:

Query Params (top priority)
Window Object (second priority)
Cookie Values (last priority)

Example

<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>

Properties

fides_clear_cookie

fides_clear_cookie: boolean

When true, deletes the fides_consent cookie when FidesJS is initialized, to clear any previously saved consent preferences from the user's device.

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_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

<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 (opens in a new tab)

Defaults to undefined.

fides_string

fides_string: string

Override the current user's fides_string consent preferences (see Fides.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,1~~61.70,DBABLA~~BVAUAAAAAWA.QA,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"

// TC and AC strings only: // "CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA,1~61.70"

// 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) or write your own function that looks something like:

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).

Note: The Notice Consent string will take precedence over 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 (opens in a new tab) *

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.

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.

FidesEvent FidesExperienceConfig