Privacy Center FidesJS Hosting (GET /fides.js)

In a production deployment (like Astralis Cloud or Astralis Serverless), the FidesJS JavaScript bundle is hosted by your Astralis 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 Astralis 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 Astralis 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 Astralis Cloud or Astralis Serverless)
2. Fetches the matching Privacy Experience from the Astralis 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 Astralis Cloud or Astralis Serverless) 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 Astralis 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 Astralis Cloud or Astralis Serverless - if so, the geolocation query param might be exactly what you're looking for!

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

• geolocation query param
• gpp query param
• property_id query param
• CloudFront-Viewer-Country request header
• CloudFront-Viewer-Country-Region request header
• Configured geolocation headers, which replace the CloudFront headers when set

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

Astralis 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. Note that this code will only match privacy experiences that are explicitly configured with EEA as their region. A Privacy Experience which uses the European Economic Area as a geolocation will not match a user who has been geolocated in France, for instance. To use EEA you must pass it as a query parameter in your fides.js src tag.

For example:

By default, the Privacy Center will look for request headers (see CloudFront-Viewer-Country, or your configured geolocation headers), 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>

initialize

optional initialize: 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

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 Astralis UI and is a short alphanumeric ID like FDS-A0B1C2.

Note that a geolocation is required when property_id is specified. Astralis 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 Astralis Cloud or Astralis Serverless, 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.

This header is also ignored when configured geolocation headers are set.

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 Astralis Cloud or Astralis Serverless, 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.

This header is also ignored when configured geolocation headers are set.

Configured geolocation headers

If your Privacy Center sits behind a CDN or proxy other than CloudFront, you can tell it which request headers carry the visitor's location with two server settings:

• FIDES_PRIVACY_CENTER__GEOLOCATION_COUNTRY_HEADER: the header holding the ISO 3166-1 alpha-2 (opens in a new tab) country code, such as US.
• FIDES_PRIVACY_CENTER__GEOLOCATION_REGION_HEADER (optional): the header holding the region code. Use only the subdivision part of the ISO 3166-2 (opens in a new tab) code, such as CA for US-CA. A full code like US-CA is ignored.

When the country header is set:

• The Privacy Center reads only the configured headers. The CloudFront headers above, and the Cloudflare CF-IPCountry and CF-Region-Code headers that the hosted Privacy Center pages otherwise read, are ignored.
• /fides.js lists the configured header names in its Vary response header, so a cache that honors Vary stores one bundle per location.
• The geolocation query parameter still takes precedence.

Header names are case-insensitive. A region header set without a country header has no effect.

Example: Cloudflare

Cloudflare's Cache Rules can vary the cache on request headers, but not on headers whose names start with cf-, so Cloudflare's own CF-IPCountry header can't be used to cache /fides.js per location. Instead, copy the visitor's location into your own headers:

1. Create a Request Header Transform Rule for your Privacy Center hostname that sets two headers:
   • x-geo-country to the expression ip.src.country
   • x-geo-region to the expression ip.src.region_code
2. Configure the Privacy Center:

   FIDES_PRIVACY_CENTER__GEOLOCATION_COUNTRY_HEADER=x-geo-country
   FIDES_PRIVACY_CENTER__GEOLOCATION_REGION_HEADER=x-geo-region
3. Create a Cache Rule for the /fides.js path that makes responses eligible for cache and sets Vary: x-geo-country and x-geo-region as passthrough, accept-language as normalize, and the default action as bypass.

Use ip.src.region_code, which returns just the subdivision (TX), rather than ip.src.subdivision_1_iso_code, which returns the full ISO 3166-2 code (GB-ENG).

To confirm the setup, request /fides.js from two different locations and check that each response contains the matching experience and that the second request for the same location is served from cache (cf-cache-status: HIT).

Related Server Settings for GET /fides.js

There are a variety of settings for fides-privacy-center that are controlled by providing FIDES_PRIVACY_CENTER__*-prefixed environment variables to the container. On Astralis Cloud or Astralis Serverless, contact Ethyca Support to request changes to these.

For the purposes of /fides.js hosting, the following settings are relevant: