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:
- Looks up the user's geolocation based on their CDN location (if hosted via Fides Cloud)
- Fetches the matching Privacy Experience from the Fides API based on the user's geolocation
- Customizes the FidesJS options based on user's Privacy Experience, "global" server settings, etc.
- 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:
geolocationquery paramgppquery paramproperty_idquery paramCloudFront-Viewer-Countryrequest headerCloudFront-Viewer-Country-Regionrequest header
Query Parameters
geolocation
optionalgeolocation:string
Override FidesJS to use a specific geolocation by providing a valid ISO 3166-2 (opens in a new tab) code:
- Starts with a 2 letter country code (e.g. "US", "GB") (see ISO 3166-1 alpha-2 (opens in a new tab))
- (Optional) Ends with a 1-3 alphanumeric character region code (e.g. "CA", "123", "X") (see ISO 3166-2 (opens in a new tab))
- 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:
| Request | Country | Region |
|---|---|---|
/fides.js?geolocation=US | United States | none |
/fides.js?geolocation=US-CA | United States | California |
/fides.js?geolocation=GB-ENG | United Kingdom | England |
/fides.js?geolocation=CZ-321 | Czechia | Domažlice |
/fides.js?geolocation=EEA | European Economic Area | none |
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
optionalgpp: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>initialize
optionalinitialize:boolean
When set to "false", the FidesJS bundle will not initialize automatically in the
user's web browser and instead will only load the JavaScript code and create the
global window.Fides interface (opens in a new tab).
Use window.Fides.init() (opens in a new tab)
to initialize manually.
Example
Disable FidesJS initialization and trigger manually instead::
<head>
<script src="https://privacy.example.com/fides.js?initialize=false"></script>
</head>
<body>
<!--- Later, in your own application code... -->
<script>Fides.init()</script>
</body>property_id
optionalproperty_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
optionalCloudFront-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
optionalCloudFront-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.