Consent Management: Install Fides JS on your Website

In this tutorial we will install fides.js, the Astralis JavaScript Components, to your website so that your visitors are served the appropriate privacy and consent notices.

In general, this will require 3 steps:

1. Adding the fides.js script tag to the source code of your website
2. Adding a link to the footer of your website to open the Astralis overlay/modal
3. Configuring your tag manager or custom JavaScript tags to enable/disable scripts

When you're done, the edits to your website should look something like this:

<head>
  <!-- (Optional) Enable Fides.js integrations, such as Google Tag Manager or Adobe Experience Manager -->
   <script>
    // Include as required
    function setupScriptLoaders() {
      window.Fides.gtm(); // if you use Google Tag Manager
      window.Fides.aep(); // if you use Adobe Experience Platform
    }
    if (typeof window.Fides !== "undefined") {
      setupScriptLoaders();
    } else {
      addEventListener("FidesReady", setupScriptLoaders);
    }
  </script>
 <!-- Include Fides.js before all other script tags that need consent -->
  <script src="https://privacy.example.com/fides.js"></script>
</head>
 
<body>
  <!-- Step Two: Add a custom link/button/etc. to the footer of your site with id="fides-modal-link" -->
  <a href="#" id="fides-modal-link">
    Manage Preferences
  </a>
</body>

Let's get started!

Prerequisites

For this tutorial you'll need:

• The role of Owner or Contributor for your Astralis organization.
• Access to the source code of your website to add JavaScript.
• At least one system with a data use on your Data Map. Read how to add systems to the Data Map now.
• At least one privacy notice configured. Read how to configure privacy notices now.
• At least one privacy experience configured. Read how to configure privacy experiences now.

Install Fides.js Script on your Website

Fides.js is the JavaScript package that powers Astralis privacy and consent experiences on your website. It needs to be installed into the source code of your website to function, which will require some small customizations to suit your preferences.

Use the following template as a guide to update your website:

<head>
  <!-- (Optional) Enable Fides.js integrations, such as Google Tag Manager or Adobe Experience Manager -->
   <script>
    // Include as required
    function setupScriptLoaders() {
      window.Fides.gtm(); // if you use Google Tag Manager
      window.Fides.aep(); // if you use Adobe Experience Platform
    }
    if (typeof window.Fides !== "undefined") {
      setupScriptLoaders();
    } else {
      addEventListener("FidesReady", setupScriptLoaders);
    }
  </script>
 <!-- Include Fides.js before all other script tags that need consent -->
  <script src="https://privacy.example.com/fides.js"></script>
</head>

Modify this template with:

1. Replace privacy.example.com with the custom domain of your privacy center, e.g. "privacy.example.com", "privacy.your-brand.com", or "privacy-your-brand.fides-cdn.ethyca.com". If you're not sure what to use, work with your Ethyca customer success team!
2. Optionally, remove the <script>Fides.gtm()</script> tag if you do not use Google Tag Manager for managing tags on your website

Test Fides.js Installation

Once you have installed the fides.js script and deployed the changes to your website, you can do some quick tests before fully configuring your consent solution. Here are three easy checks:

1. Open your updated website in your web browser, e.g. https://www.example.com (opens in a new tab)
2. Inspect the source code of your website and ensure that the <script src="https://privacy.example.com/fides.js"></script> is present
3. Open the Developer Console and run window.Fides and ensure that you see a valid Javascript object like:

{consent: {…}, experience: undefined, geolocation: undefined, options: {…}, fides_meta: {…}, …}

If window.Fides is loading, you're almost done!

Step Two: Add a Link or Button to Your Website Footer

For full consent compliance, it's often necessary to have a link or button on your site so that your website visitors can directly manage their consent preferences. Commonly, this will be a link or button element in the footer like "Manage Preferences", "Your Privacy Choices", or similar. The following documents both a simple and then an advanced implementation.

Basic Install

This implementation will cover the majority of use cases. You can either edit an existing element, or add a new element on your page to show the Astralis consent overlay by using id="fides-modal-link" on that element:

<body>
  <!-- Step Two (simple): Add a custom link/button/etc. to the footer of your site with id="fides-modal-link" -->
  <a href="#" id="fides-modal-link">
    Manage Preferences
  </a>
</body>

Once you have added this link or button and deployed the changes to your website, Fides.js will automatically look for the element by searching for id="fides-modal-link".

You should be able to click the link and open the Astralis overlay! Note that Astralis will automatically hide that link by default, and will only show if there are relevant notices in the user's location.

Advanced Install

For more complex or advanced use cases, Fides.js exposes some methods to allow for more control over the interaction between Fides.js and your application. You can either edit an existing element, or add a new element on your page to show the Astralis consent overlay by adding an onclick event and a custom class to help display that element correctly:

<body>
  <!-- Step Two (advanced): Add a custom link/button/etc. to the footer of your site -->
  <a href="#" class="my-custom-link" onclick="Fides.showModal()">
    Manage Preferences
  </a>
</body>

Astralis will also add a class (fides-overlay-modal-link-shown) to the body to be used to control visibility of the footer link. The following is an example of how to use that class to control when the footer link should be visible:

  /* Hide the modal link by default */
  .my-custom-link {
    display: none;
  }
  /* Only show the modal link when applicable */
  .fides-overlay-modal-link-shown .my-custom-link {
    display: inline;
  }

You should be able to click the link and open the Astralis overlay! Note that Astralis will automatically hide that link by default, and will only show if there are relevant notices in the user's location.

(Optional) Install the TCF CMP Stub

If you are using the IAB Transparency and Consent Framework (TCF), downstream ad scripts often expect the window.__tcfapi function to be available immediately when they load. Because fides.js is loaded asynchronously, there can be a brief window where __tcfapi is not yet defined, causing errors in ad scripts that depend on it.

To solve this, Astralis provides fides-stub.js, which contains the official IAB TCF CMP stub (opens in a new tab). This lightweight script:

• Defines window.__tcfapi immediately so ad scripts can call it without errors
• Queues any API calls until the full CMP (fides.js) loads and takes over
• Supports the ping command so scripts can detect the CMP is loading
• Handles cross-frame postMessage communication for cross-origin iframes

Add the stub script tag before your fides.js tag:

<head>
  <!-- Load the TCF CMP stub first so __tcfapi is available immediately -->
  <script src="https://privacy.example.com/fides-stub.js"></script>
  <!-- Then load fides.js, which replaces the stub and replays queued calls -->
  <script src="https://privacy.example.com/fides.js"></script>
</head>

Configuring Google Tag Manager

Now that you've installed Fides.js and added the modal link, you're ready for the next step - configuring your tag manager!

See Configuring Google Tag Manager now!

(Optional) Integrating Fides.js with Custom JavaScript

For tags that are managed outside of a Tag Manager, or any other custom code which requires user consent, you can check the user’s consent directly in the Fides.consent global variable.

For example, to check the user's consent state before loading any on-page scripts, you could use an approach like this:

// example function for loading scripts 
function conditionallyLoadScripts() {
    // Check the relevant consent flag
    // In this example, data_sales_and_sharing
    if (Fides.consent.data_sales_and_sharing) {
        // Load script(s)
    }
}
 
if (Fides?.initialized) {
    // To make sure this script loads if `FidesReady` was dispatched
    // before your script loader runs.
    conditionallyLoadScripts();
} else {
    // To make sure the script loads if your script loader ran before 
    // Fides was initialized.
    addEventListener("FidesReady", conditionallyLoadScripts);
}
 
// If the user is opted out, and then opts in, make sure to run your script loader.
addEventListener("FidesUpdated", conditionallyLoadScripts);

This example adds event listeners (opens in a new tab) to FidesReady and FidesUpdated to ensure scripts are loaded only after Astralis is ready or when the user's consent state changes.

Stop scripts when the user opts out

The example above loads a script when the user opts in, but it doesn't handle the reverse. Once a script is loaded, it keeps running until the page reloads. If the user opts out after that, you need to tell the script to stop.

The following example handles both directions. It loads the script the first time the user opts in, pauses it when the user opts out, and resumes it if the user opts back in:

let scriptLoaded = false;
 
function applyConsent() {
    // In this example, data_sales_and_sharing
    const hasConsent = Fides.consent.data_sales_and_sharing === true;
 
    if (hasConsent && !scriptLoaded) {
        // First opt in: load the script(s)
        scriptLoaded = true;
    } else if (hasConsent) {
        // Already loaded: resume the script using the vendor's own consent API
    } else if (scriptLoaded) {
        // Opted out after the script loaded: stop or pause it using the vendor's own consent API
    }
}
 
if (Fides?.initialized) {
    applyConsent();
} else {
    addEventListener("FidesReady", applyConsent);
}
 
// Runs on every consent change, including opt out
addEventListener("FidesUpdated", applyConsent);

FidesUpdated is dispatched for any change to the user's consent, not only the notice your script depends on. Write your handler so it is safe to run more than once with the same consent value.

How you pause or resume a script depends on the vendor. Many advertising and analytics tools provide a consent API for this, such as the Meta Pixel consent controls described below. If a vendor has no such API, the only way to stop it fully is to reload the page.

Here’s an example of how you can check the user's consent state before triggering any custom on-page interactions:

// Example for interaction tracking:
 
var someButton = document.getElementById("some-button-id");
someButton.addEventListener("click", () => {
    if (Fides?.consent?.data_sales_and_sharing) {
        // Track interaction
    }
});

Note that, in the above examples, data_sales_and_sharing matches a cookie key for a privacy notice created when configuring consent management in the Admin UI. The cookie key can be any unique identifier you choose when creating a privacy notice.

Read about creating cookie keys as part of privacy notices here.

Single page apps

A single page app (SPA) loads the page once and then updates it in place as the user navigates. The browser never reloads the page, so code that only checks consent on page load runs once and never again. This affects consent in three ways:

• Handle consent with events, not just a check on page load. Listen for FidesUpdated so your code runs every time the user changes their consent, as shown in Stop scripts when the user opts out. A check that only runs on page load will miss any change the user makes afterwards.
• Pause running scripts on opt out, and resume them on opt in. A script loaded after an earlier opt in stays in memory for the rest of the session. When the user opts out, call the vendor's consent API to pause it. When the user opts back in, resume it rather than loading it a second time.
• Cookies can come back. When the user opts out, Astralis deletes the cookies associated with that notice. A script that is still running doesn't know this and can set the same cookies again on the next navigation or interaction. If Continuous cookie deletion is on for your experience, Astralis blocks scripts from setting those cookies again. Either way, the script keeps sending data until you pause it.

For example, if you load the Meta Pixel only after the user opts in, and the user later opts out, Astralis deletes the _fbp cookie. Unless the pixel is told to stop, it keeps sending events to Meta. If Continuous cookie deletion is off, it also sets _fbp again on the next page the user visits in your app. See Meta Pixel for how to handle this.

Meta Pixel

If you load the Meta Pixel yourself, add a FidesUpdated listener that passes the user's consent to the pixel using Meta's own consent controls. This keeps the pixel in line with the user's choice when they change their mind, including on a single page app.

window.addEventListener("FidesUpdated", () => {
  if (!window.fbq) return;
  const ok = window.Fides.consent.sales_sharing_targeted_advertising === true;
  if (window.Fides.geolocation?.country === "US") {
    window.fbq("dataProcessingOptions", ok ? [] : ["LDU"], 0, 0);
  } else {
    window.fbq("consent", ok ? "grant" : "revoke");
  }
});

In this example, sales_sharing_targeted_advertising is a placeholder. Replace it with the cookie key of the privacy notice that covers the Meta Pixel in your organization. Read about creating cookie keys as part of privacy notices.

This listener handles changes to consent. Your script loader still decides whether the pixel loads in the first place, as in the custom JavaScript example above.

Outside the US

fbq("consent", "revoke") stops the pixel completely. It sends no events, and it doesn't set the _fbp or _fbc cookies again. fbq("consent", "grant") turns the pixel back on.

In the US

In the US, the listener sends Meta's Limited Data Use (LDU) (opens in a new tab) signal instead. LDU is Meta's standard way to handle an opt out of the sale of personal data in the US. The two 0 values tell Meta to work out the user's state from their location.

With LDU, the pixel keeps running. If Continuous cookie deletion is off, _fbp can come back after the user opts out. This is expected. Meta limits how it uses the data it receives with the LDU signal.

If you want the pixel fully off for US users who opt out as well, use revoke everywhere instead of LDU:

window.addEventListener("FidesUpdated", () => {
  if (!window.fbq) return;
  const ok = window.Fides.consent.sales_sharing_targeted_advertising === true;
  window.fbq("consent", ok ? "grant" : "revoke");
});

This is stricter, but you lose ad data from US users who opt out.

Don't create fbq yourself

The line if (!window.fbq) return; matters. If the pixel hasn't loaded yet, there's nothing to tell, so the listener does nothing. Don't define window.fbq yourself to queue the call. Many pixel loaders skip loading Meta's script if window.fbq already exists, so creating it means the pixel never loads after a later opt in.

Conversions API

If you also send events to Meta from your server through the Conversions API (opens in a new tab), the browser settings above don't apply to those events. Your server needs to respect the user's opt out, and send the LDU signal for US users, in the same way.

Test your setup

• Use the Meta Ads Data Advisor Chrome extension to check the pixel's consent and LDU state after you opt in and out.
• In your browser's DevTools, watch the _fbp cookie under Application → Cookies, and filter the Network tab for requests to facebook.com/tr. Outside the US, these requests should stop after you opt out.

For more detail, see Meta's documentation on the pixel and GDPR (opens in a new tab) and data processing options (opens in a new tab).

If you use Google Tag Manager to load the Meta Pixel, see Configure Limited Data Use for Meta (Facebook) for the equivalent setup.