Fides Documentation – Ethyca

Interface: Fides

Once FidesJS is initialized, it exports this global object to window.Fides as the main API to integrate into your web applications.

You can then use Fides in your JavaScript code to check the user's current consent preferences (e.g. if (Fides.consent.marketing) { ... }), enable FidesJS integrations (e.g. Fides.gtm()), programmaticaly show the FidesJS UI (e.g. Fides.showModal()) and more. See the full list of properties below for details.

NOTE: FidesJS will need to be downloaded, executed, and initialized before the Fides object is available. Therefore, your code should check for the existence of Fides or subscribe to the global FidesReady event (see FidesEvent) for details) before using the Fides object in your own code.

Example Permalink for this section

<head>
  <script src="path/to/fides.js"></script>
</head>
<body>
  <!--- ...later, in your own application code... --->
  <script>
    // Query the current user's consent preferences
    if (Fides && Fides.consent.data_sales_and_sharing) {
      // Enable advertising scripts
      console.log("Current user has opt-in consent for the `data_sales_and_sharing` privacy notice!");
    }
  </script>
</body>

Properties Permalink for this section

consent Permalink for this section

consent: Record<string, string | boolean>

User's current consent preferences, formatted as a key/value object with:

key: the applicable Fides notice_key (e.g. data_sales_and_sharing, analytics)
value:
- true or false boolean values (where true means opt-in/consent granted, false means opt-out/consent declined)
- or one of these string values:
  - "opt_in" - user has explicitly opted in to this notice
  - "opt_out" - user has explicitly opted out of this notice
  - "acknowledge" - user has acknowledged this notice (for notice-only consent mechanisms)
  - "not_applicable" - notice is not applicable to the user's region/context

Note that FidesJS will automatically set default consent preferences based on the type of notice - so, for example a typical "opt-in" analytics notice will be given a default value of false. This allows writing very simple (and readable!) code to check a user's consent preferences.

The specific keys provided in the Fides.consent property are determined based on your Fides configuration, and are provided to the browser based on the user's location, property ID, etc.

Examples Permalink for this section

A Fides.consent value showing the user has opted-out of data sales & sharing:

{
  "data_sales_and_sharing": false
}

A Fides.consent value showing the user has opted-in to analytics, but not marketing:

{
  "analytics": true,
  "marketing": false
}

A Fides.consent value showing the user has opted-in to analytics, but not marketing using consent mechanism strings:

{
  "analytics": "opt_in",
  "marketing": "opt_out"
}

A Fides.consent value showing a notice-only consent mechanism with acknowledgment:

{
  "terms_of_service": "acknowledge"
}

fides_string? Permalink for this section

optional fides_string: string

User's current consent string(s) combined into a single value. This is used by FidesJS to store IAB consent strings from various frameworks such as TCF, GPP, and Google's "Additional Consent" string. Additionally, we support passing a Notice Consent string, which is a base64 encoded string of the user's Notice Consent preferences.

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 Permalink for this section

console.log(Fides.fides_string);
// "CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA,2~61.70~dv.33,DBABLA~BVAUAAAAAWA.QA,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"

initialized Permalink for this section

initialized: boolean

Whether or not FidesJS has finished initialization and has loaded the current user's experience, consent preferences, etc.

updateConsent() Permalink for this section

updateConsent: (options) = Promise<void>

Updates user consent preferences with either a consent object or fidesString. If both are provided, fidesString takes priority.

Parameters Permalink for this section

Parameter	Type	Description
`options`	{ `consent`: `Record`<`string`, `string`	`boolean`>; `fidesString`: `string`; `validation`: "throw"
`options.consent`?	`Record`<`string`, `string`	`boolean`>
`options.fidesString`?	`string`	A Fides string containing encoded consent preferences
`options.validation`?	"throw"	"warn"

Returns Permalink for this section

Promise<void>

Examples Permalink for this section

Update consent using notice keys and boolean values:

Fides.updateConsent({
  consent: {
    data_sales_and_sharing: false,
    analytics: true
  }
});

Update consent using string values instead of booleans:

Fides.updateConsent({
  consent: {
    data_sales_and_sharing: "opt_out",
    analytics: "opt_in",
    terms_of_service: "acknowledge"
  }
});

Update consent using a fidesString:

Fides.updateConsent({
  fidesString: ",,,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"
});

Control validation behavior:

// With validation="warn" - logs warnings but doesn't throw errors
Fides.updateConsent({
  consent: { notice_key: invalidValue },
  validation: "warn"
});

// With validation="ignore" - silently accepts invalid values
Fides.updateConsent({
  consent: { notice_key: invalidValue },
  validation: "ignore"
});