# 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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/FidesEvent/index.html)) for details) before using the `Fides` object in your own code.

## Example [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#example/index.html)

```html
<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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#properties/index.html)

### consent [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#consent/index.html)

> **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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#examples/index.html)

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

```json
{
  "data_sales_and_sharing": false
}
```

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

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

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

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

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

```json
{
  "terms_of_service": "acknowledge"
}
```

### fides_string? [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#fides_string/index.html)

> `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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#example-1/index.html)

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

### initialized [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#initialized/index.html)

> **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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#updateconsent/index.html)

> **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](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#parameters-11/index.html)
| Parameter | Type | Description |
| --- | --- | --- |
| `options` | { `consent`: `Record`<`string`, `string` | `boolean`>; `fidesString`: `string`; `validation`: "throw" | "warn" | "ignore"; } | Options for updating consent |
| `options.consent`? | `Record`<`string`, `string` | `boolean`> | Object mapping notice keys to consent values: - Boolean values: `true` (opt-in/consent granted) or `false` (opt-out/consent declined) - String values: - "opt_in" - user has explicitly opted in to this notice - "opt_out" - user has explicitly opted out of this notice - "acknowledge" - ONLY valid for notices with "notice_only" consent mechanism |
| `options.fidesString`? | `string` | A Fides string containing encoded consent preferences |
| `options.validation`? | "throw" | "warn" | "ignore" | Controls validation behavior: "throw" (default), "warn", or "ignore" - "throw": Throws an error if any consent value is invalid (default) - "warn": Logs a warning if any consent value is invalid, but continues processing - "ignore": Silently accepts invalid values without validation |

#### Returns [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#returns-15/index.html)
`Promise`<`void`>

#### Examples [Permalink for this section](/content/docs/privacy-center-fidesjs/fidesjs/reference/interfaces/Fides#examples-9/index.html)

Update consent using notice keys and boolean values:
```javascript
Fides.updateConsent({
  consent: {
    data_sales_and_sharing: false,
    analytics: true
  }
});
```

Update consent using string values instead of booleans:
```javascript
Fides.updateConsent({
  consent: {
    data_sales_and_sharing: "opt_out",
    analytics: "opt_in",
    terms_of_service: "acknowledge"
  }
});
```

Update consent using a fidesString:
```javascript
Fides.updateConsent({
  fidesString: ",,,eyJkYXRhX3NhbGVzX2FuZF9zaGFyaW5nIjowLCJhbmFseXRpY3MiOjF9"
});
```

Control validation behavior:
```javascript
// 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"
});
```