Fides.js: a little script for a lot of privacy!

The past few months, the Ethyca engineering team has been building out a user consent feature for Fides, our open-source privacy engineering platform. Our goal was to provide a small script that can be inserted onto any website and handle all of its user consent needs. The script can serve a consent banner, render data use notices, delete cookies from the browser, honor GPC signals, dispatch window events, and more—all in less than 20kb!

Let’s go through what this looks like in practice and how we built this. 👷‍♀️

What this looks like

Let’s say you are a vendor of cookies (the yummy kind 🍪, not the browser kind). Once configured on your site, fides.js looks like the following:

At this point, fides.js has queried for the user’s location and figured out what a user needs to consent to. fides.js can render a banner on top of your existing website. The user can make their consent choices right there, or they can click “Manage preferences” to see the details of what they are consenting to.

Once the user saves their preferences, a few things happen:

• The user’s preferences are saved to the server so that the next time they visit the page, the banner will not render. Additionally, it is saved for consent reporting purposes.
• The user’s preferences are saved to a cookie on the browser for fast initialization ⚡
• The user’s preferences are saved to a window.Fides object. This makes it easy for other code on your site to query for the user’s consent status.
• A FidesUpdated browser event is dispatched. This means your own website code can listen for this event and act accordingly.
  • For example, if your site runs Google Tag Manager, and the FidesUpdated event indicates the user opted out of advertising, then you can listen for the event and turn off GTM in the browser. This allows for easy integration between Fides and your web application
• If a user opted out of a notice that has cookies associated with it (for example, Google Analytics might use a _ga cookie but the user opts out of tracking), then fides.js will delete those cookies from the user’s browser.

fides.js will also honor Global Privacy Controls and automatically opt users out of notices that can be opted out via GPC:

To top it off, all of the copy and much of the design you see here can be customized!

Critically, the fides.js banner and modal are also accessible and follow the specifications outlined by the WCAG. As such, it is fully keyboard navigable, among other accessibility best practices.

So how does all this work?

What’s happening behind the scenes

Let’s say your cookie venture operates in the United States. You may have heard something about various data privacy laws being passed in different states, such as California’s CCPA or Virginia’s VCDPA, and you want to make sure you’re complying with the law (after all, the good citizens of CA and VA need your cookies!). But you really don’t want to think about all of the complicated legalese or the specific details of each law. So, you turn to Fides to do it for you.

In Fides, you can specify that you, for example, use Google Analytics for first party advertising.

Fides takes care of knowing what you need to disclose when you use first party advertising. We call these “Privacy Notices”—the individual data uses that your users can opt in and out of. We’ve read all the privacy laws, and so we know that, if your user is coming from California, you need to enable users to opt out of “Data Sales and Sharing.” Fides automatically does this for you! Fides ships with templates based on established privacy laws around the world so that you do not have to worry about them 😌

Separate from the individual notices which contain data uses users can opt out of, Fides also has a notion of a “Privacy Experience”. A Privacy Experience is meant to allow you to customize all the copy surrounding your notices—what the banner’s title is, what the buttons should say, etc.

Once you’ve filled in all the ways you use data (perhaps you use Salesforce to keep track of leads, or Postgres to save customer data), Fides takes care of the rest. Because Fides knows you use first party advertising, it will make sure the user can consent to data sales and sharing. You can copy a script tag into your site.

And that’s it for configuration! But what exactly is fides.js doing on your web page?

Fides.js lifecycle on your page

1. Your page loads fides.js.
2. fides.js determines the user’s location.
3. fides.js makes a call to the Fides server to see what privacy experience + notices it needs to render based on the user’s location.
4. You can optionally include an element with an id of fides-modal-link. If fides.js sees that this link exists, it will attach an event handler to open the preferences modal when that link is clicked.
5. fides.js sends a FidesInitialized and FidesUpdated event in the browser
6. If fides.js detects a Global Privacy Control signal, it will automatically opt the user out of relevant notices
7. If needed based on the experience configuration, fides.js renders a banner overlay, which in turn can open the preferences modal.

After this, fides.js does not do anything until the user takes an action (opts in or out of notices). We’ve already gone through what fides.js does after a user action, but to recap, it:

1. Saves preferences to a cookie on the page
2. Saves preferences to a window.Fides object
3. Saves preferences to the Fides server
4. Issues a FidesUpdated event
5. Deletes cookies if needed

Throughout this process, there is always a window.Fides object that can be queried with up to date data about the user’s consent preferences. If they have opted out of data sales and sharing, then the window.Fides object would look like:

{
  consent: {
    data_sales_and_sharing: false
  }
}

The key data_sales_and_sharing is also configurable from the Admin UI. This makes it straightforward for your application to figure out what a user has opted into!

And of course, if you would like to customize the colors of the banner and modal, you can include a small CSS file that changes some CSS variables. For example, if you are releasing a new tomato cookie, perhaps you would want to change your branding to:

--fides-overlay-primary-color: tomato

Okay but what is fides.js really doing on your page?

Before you include a random script off the internet onto your webpage, it’s understandable that you’d want to know exactly what it’s doing! We totally get that, which is why fides.js is a small open source TypeScript module which you can peruse as much as you’d like! It uses Preact to keep things small, rollup for bundling, and jest and Cypress for testing.

We welcome pull requests and issues in our GitHub repo as we strive to make trust and privacy the default for the internet 💙

What’s next?

The Fides consent journey is far from over, and we have big plans for this small package, including:

• Trust and Consent support
• Global Privacy Platform support

Stay tuned for more updates! In the meantime, check out our website for an overview of our consent product and to book a demo!