Skip to content
Developer Docs
FidesJS
Privacy Center FidesJS Hosting

Privacy Center FidesJS Hosting (GET /fides.js)

In a production deployment (like Fides Cloud), the FidesJS JavaScript bundle is hosted by your Fides Privacy Center so that it can be customized for your users when added to your website. For example, if your Privacy Center is at https://privacy.example.com, you might add the following script tag to your website to add FidesJS:

<head>
  <script src="https://privacy.example.com/fides.js?geolocation=US-CA"></script>
</head>

For most usage, this default script tag will be sufficient, and you should follow the Install Fides on your website guide to get started. However, there are additional developer options available, so read on to learn about server-side bundling, advanced request options, and more.

Privacy Center Server-Side Bundling

The Fides Privacy Center is more than a static filehost: it's a mini-API that customizes the FidesJS bundle server-side to maximize your website performance!

In fact, every time /fides.js is requested, the Privacy Center:

  1. Looks up the user's geolocation based on their CDN location (if hosted via Fides Cloud)
  2. Fetches the matching Privacy Experience from the Fides API based on the user's geolocation
  3. Customizes the FidesJS options based on user's Privacy Experience, "global" server settings, etc.
  4. Returns a customized JavaScript bundle for the user with all configuration inlined

This means the critical per-user configuration logic for consent can be performed server-side and inlined into the resulting fides.js JavaScript bundle. These bundles can then be cached per-geolocation using a CDN (e.g. CloudFront, Fastly) to ensure that the download speeds are also optimized, leading to improved pageload performance and happier users.

This server-side logic can be overridden by adjusting some server settings (contact Ethyca Support for assistance here on Fides Cloud) or by supplying some advanced request options as request params when adding the /fides.js script tag to your website.

Advanced Request Options for GET /fides.js

Depending on your own application's needs, you may want to override some of the default behavior of the Fides Privacy Center's server-side bundling. For example, you may already have a method for geolocating users that you would like to leverage instead of using Fides Cloud - if so, the geolocation query param might be exactly what you're looking for!

The /fides.js endpoint supports the following advanced request options:

Query Parameters

geolocation

optional geolocation: string

Override FidesJS to use a specific geolocation by providing a valid ISO 3166-2 (opens in a new tab) code:

  1. Starts with a 2 letter country code (e.g. "US", "GB") (see ISO 3166-1 alpha-2 (opens in a new tab))
  2. (Optional) Ends with a 1-3 alphanumeric character region code (e.g. "CA", "123", "X") (see ISO 3166-2 (opens in a new tab))
  3. Country & region codes must be separated by a hyphen (e.g. "US-CA")

Fides also supports a special EEA geolocation code to denote the European Economic Area; this is not part of ISO 3166-2, but is supported for convenience.

For example:

RequestCountryRegion
/fides.js?geolocation=USUnited Statesnone
/fides.js?geolocation=US-CAUnited StatesCalifornia
/fides.js?geolocation=GB-ENGUnited KingdomEngland
/fides.js?geolocation=CZ-321CzechiaDomažlice
/fides.js?geolocation=EEAEuropean Economic Areanone

By default, the Privacy Center will look for request headers (see CloudFront-Viewer-Country), but this query param acts as an override. If neither request headers nor this param are present, the Privacy Center will fallback to not fully configuring FidesJS server-side and rely on client-side geolocation to finish configuration.

Example

Override FidesJS to be set to California (US-CA):

<head>
  <script src="https://privacy.example.com/fides.js?geolocation=US-CA"></script>
</head>

gpp

optional gpp: boolean

Forces the Global Privacy Platform (GPP) (opens in a new tab) extension to be included in the FidesJS bundle, even if the experience does not have GPP enabled. This allows the __gpp API to always be available for all FidesJS experiences.

Defaults to false.

Example

Override FidesJS to be always include GPP:

<head>
  <script src="https://privacy.example.com/fides.js?gpp=true"></script>
</head>

property_id

optional property_id: string

Select a specific property to use for FidesJS when finding a matching Privacy Experience. This property_id can be found on the Properties page in the Fides UI and is a short alphanumeric ID like FDS-A0B1C2.

Note that a geolocation is required when property_id is specified. Fides Cloud will detect this normally via request headers, but if you are also using the geolocation query param, it's important to ensure you supply a valid location code whenever using property_id as well!

Defaults to undefined.

Example

Specify the property ID FDS-A0B1C2:

<head>
  <script src="https://privacy.example.com/fides.js?property_id=FDS-A0B1C2"></script>
</head>

Request Headers

CloudFront-Viewer-Country

optional CloudFront-Viewer-Country: string

ISO-3166-1 alpha-2 (opens in a new tab) country code to use for geolocation. This header is added to requests originating from a CloudFront distribution (see the AWS documentation for Adding CloudFront request headers (opens in a new tab) for details).

If you are using Fides Cloud, this header will be included by default for all requests routed through our CDN.

If the geolocation query parameter is also provided, the query param will take precedence and this header will be ignored.

CloudFront-Viewer-Country-Region

optional CloudFront-Viewer-Country-Region: string

ISO-3166-2 (opens in a new tab) region code to use for geolocation. This header is added to requests originating from a CloudFront distribution - see Adding CloudFront request headers (opens in a new tab) for details.

If you are using Fides Cloud, this header will be included by default for all requests routed through our CDN.

If the geolocation query parameter is provided, the query param will take precedence and this header will be ignored.

FidesOptionsDatasets