Dispatch Fides.js lifecycle events on window (FidesInitialized, FidesUpdated) and cross-publish to Fides.gtm() integration

clients/fides-js/src/fides.ts

@@ -72,9 +72,10 @@ import {
   transformConsentToFidesUserPreference,
   validateOptions,
 } from "./lib/consent-utils";
+import { dispatchFidesEvent } from "./lib/events";
 import { fetchExperience } from "./services/fides/api";
 import { getGeolocation } from "./services/external/geolocation";
-import { OverlayProps } from "~/components/Overlay";
+import { OverlayProps } from "./components/Overlay";
 import { updateConsentPreferences } from "./lib/preferences";
 
 export type Fides = {
@@ -250,6 +251,12 @@ const init = async ({
   _Fides.options = options;
   _Fides.initialized = true;
 
+  // Dispatch the "FidesInitialized" event to update listeners with the initial
+  // state. For convenience, also dispatch the "FidesUpdated" event; this allows
+  // listeners to ignore the initialization event if they prefer
+  dispatchFidesEvent("FidesInitialized", cookie);
+  dispatchFidesEvent("FidesUpdated", cookie);
+
   automaticallyApplyGPCPreferences(
     cookie,
     fidesRegionString,
@@ -287,14 +294,15 @@ if (typeof window !== "undefined") {
 
 // Export everything from ./lib/* to use when importing fides.mjs as a module
 // TODO: pretty sure we need ./services/* too?
-export * from "./lib/consent";
 export * from "./components";
+export * from "./lib/consent";
 export * from "./lib/consent-context";
 export * from "./lib/consent-types";
 export * from "./lib/consent-links";
 export * from "./lib/consent-utils";
 export * from "./lib/consent-value";
 export * from "./lib/cookie";
+export * from "./lib/events";
 
 // DEFER: this default export isn't very useful, it's just the Fides type
 export default Fides;

clients/fides-js/src/integrations/gtm.ts

@@ -1,19 +1,56 @@
+import { CookieKeyConsent } from "../lib/cookie";
+import { FidesEventDetail } from "../lib/events";
+
 declare global {
   interface Window {
     dataLayer?: any[];
   }
 }
 
 /**
- * Call Fides.gtm to configure Google Tag Manager. The user's consent choices will be
- * pushed into GTM's `dataLayer` under `Fides.consent`.
+ * Defines the structure of the Fides variable pushed to the GTM data layer
  */
-export const gtm = () => {
+interface FidesVariable {
+  consent: CookieKeyConsent;
+}
+
+// Helper function to push the Fides variable to the GTM data layer from a FidesEvent
+const pushFidesVariableToGTM = (fidesEvent: {
+  type: string;
+  detail: FidesEventDetail;
+}) => {
+  // Initialize the dataLayer object, just in case we run before GTM is initialized
   const dataLayer = window.dataLayer ?? [];
   window.dataLayer = dataLayer;
-  dataLayer.push({
-    Fides: {
-      consent: window.Fides.consent,
-    },
-  });
+
+  // Construct the Fides variable that will be pushed to GTM
+  const Fides: FidesVariable = {
+    consent: fidesEvent.detail.consent,
+  };
+
+  // Push to the GTM dataLayer
+  dataLayer.push({ event: fidesEvent.type, Fides });
+};
+
+/**
+ * Call Fides.gtm() to configure the Fides <> Google Tag Manager integration.
+ * The user's consent choices will automatically be pushed into GTM's
+ * `dataLayer` under `Fides.consent` variable.
+ */
+export const gtm = () => {
+  // Listen for Fides events and cross-publish them to GTM
+  window.addEventListener("FidesInitialized", (event) =>
+    pushFidesVariableToGTM(event)
+  );
+  window.addEventListener("FidesUpdated", (event) =>
+    pushFidesVariableToGTM(event)
+  );
+
+  // If Fides was already initialized, publish a synthetic event immediately
+  if (window.Fides?.initialized) {
+    pushFidesVariableToGTM({
+      type: "FidesInitialized",
+      detail: { consent: window.Fides.consent },
+    });
+  }
 };

clients/fides-js/src/integrations/meta.ts

@@ -82,6 +82,8 @@ type MetaOptions = {
 /**
  * Call Fides.meta to configure Meta Pixel tracking.
  *
+ * DEFER: Update this integration to support async Fides events
+ *
  * @example
  * Fides.meta({
  *   consent: Fides.consent.data_sales,

clients/fides-js/src/integrations/shopify.ts

@@ -33,6 +33,8 @@ const applyOptions = (options: ShopifyOptions) => {
  * Call Fides.shopify to configure Shopify customer privacy. Currently the only consent option
  * Shopify allows to be configured is user tracking.
  *
+ * DEFER: Update this integration to support async Fides events
+ *
  * @example
  * Fides.shopify({ tracking: Fides.consent.data_sales })
  */

clients/fides-js/src/lib/events.ts

@@ -0,0 +1,52 @@
+import { FidesCookie } from "./cookie";
+
+/**
+ * Defines the available event names:
+ * - FidesInitialized: dispatched when initialization is complete, from Fides.init()
+ * - FidesUpdated: dispatched when preferences are updated, from updateConsentPreferences() or Fides.init()
+ */
+export type FidesEventType = "FidesInitialized" | "FidesUpdated";
+
+// Bonus points: update the WindowEventMap interface with our custom event types
+declare global {
+  interface WindowEventMap {
+    FidesInitialized: FidesEvent;
+    FidesUpdated: FidesEvent;
+  }
+}
+
+/**
+ * Defines the properties available on event.detail. As of now, these are an
+ * explicit subset of properties from the Fides cookie
+ * TODO: add identity and meta?
+ */
+export type FidesEventDetail = Pick<FidesCookie, "consent">;
+
+export type FidesEvent = CustomEvent<FidesEventDetail>;
+
+/**
+ * Dispatch a custom event on the window object, providing the current Fides
+ * state on the "detail" property of the event.
+ *
+ * Example usage:
+ * ```
+ * window.addEventListener("FidesUpdated", (evt) => console.log("Fides.consent updated:", evt.detail.consent));
+ * ```
+ *
+ * The snippet above will print a console log whenever consent preferences are initialized/updated, like:
+ * ```
+ * Fides.consent updated: { data_sales_and_sharing: true }
+ * ```
+ */
+export const dispatchFidesEvent = (
+  type: FidesEventType,
+  cookie: FidesCookie
+) => {
+  if (typeof window !== "undefined" && typeof CustomEvent !== "undefined") {
+    // Pick a subset of the Fides cookie properties to provide as event detail
+    const { consent }: FidesEventDetail = cookie;
+    const detail: FidesEventDetail = { consent };
+    const event = new CustomEvent(type, { detail });
+    window.dispatchEvent(event);
+  }
+};

clients/fides-js/src/lib/preferences.ts

@@ -6,6 +6,7 @@ import {
 } from "./consent-types";
 import { debugLog, transformUserPreferenceToBoolean } from "./consent-utils";
 import { CookieKeyConsent, FidesCookie, saveFidesCookie } from "./cookie";
+import { dispatchFidesEvent } from "./events";
 import { patchUserPreferenceToFidesServer } from "../services/fides/api";
 
 /**
@@ -49,6 +50,10 @@ export const updateConsentPreferences = ({
     });
   });
 
+  // Update the cookie object
+  // eslint-disable-next-line no-param-reassign
+  cookie.consent = consentCookieKey;
+
   // 1. Save preferences to Fides API
   debugLog(debug, "Saving preferences to Fides API");
   const privacyPreferenceCreate: PrivacyPreferencesRequest = {
@@ -67,9 +72,12 @@ export const updateConsentPreferences = ({
 
   // 2. Update the window.Fides.consent object
   debugLog(debug, "Updating window.Fides");
-  window.Fides.consent = consentCookieKey;
+  window.Fides.consent = cookie.consent;
 
   // 3. Save preferences to the cookie
   debugLog(debug, "Saving preferences to cookie");
-  saveFidesCookie({ ...cookie, consent: consentCookieKey });
+  saveFidesCookie(cookie);
+
+  // 4. Dispatch a "FidesUpdated" event
+  dispatchFidesEvent("FidesUpdated", cookie);
 };

clients/privacy-center/cypress/e2e/consent-banner.cy.ts

@@ -129,6 +129,7 @@ describe("Consent banner", () => {
         cy.get("#fides-modal-link").should("not.be.visible");
       });
     });
+
     describe("when only legacy consent exists", () => {
       beforeEach(() => {
         stubConfig(
@@ -500,6 +501,7 @@ describe("Consent banner", () => {
           });
       });
     });
+
     describe("when GPC flag is found, and no notices apply to GPC", () => {
       beforeEach(() => {
         cy.on("window:before:load", (win) => {
@@ -558,6 +560,7 @@ describe("Consent banner", () => {
         cy.getCookie(CONSENT_COOKIE_NAME).should("not.exist");
       });
     });
+
     describe("when no GPC flag is found, and notices apply to GPC", () => {
       beforeEach(() => {
         cy.on("window:before:load", (win) => {
@@ -618,6 +621,7 @@ describe("Consent banner", () => {
         cy.getCookie(CONSENT_COOKIE_NAME).should("not.exist");
       });
     });
+
     describe("when experience component is not an overlay", () => {
       beforeEach(() => {
         stubConfig({
@@ -934,4 +938,140 @@ describe("Consent banner", () => {
       });
     });
   });
+
+  describe("when listening for fides.js events", () => {
+    beforeEach(() => {
+      cy.getCookie(CONSENT_COOKIE_NAME).should("not.exist");
+      stubConfig({
+        options: {
+          isOverlayDisabled: false,
+        },
+      });
+    });
+    // NOTE: See definition of cy.visitConsentDemo in commands.ts for where we
+    // register listeners for these window events
+    it("emits both a FidesInitialized and FidesUpdated event when initialized", () => {
+      cy.window()
+        .its("Fides")
+        .its("consent")
+        .should("eql", {
+          [PRIVACY_NOTICE_KEY_1]: false,
+          [PRIVACY_NOTICE_KEY_2]: false,
+        });
+      cy.get("@FidesInitialized")
+        .should("have.been.calledOnce")
+        .its("firstCall.args.0.detail")
+        .should("deep.equal", {
+          consent: {
+            [PRIVACY_NOTICE_KEY_1]: false,
+            [PRIVACY_NOTICE_KEY_2]: false,
+          },
+        });
+      cy.get("@FidesUpdated")
+        .should("have.been.calledOnce")
+        .its("firstCall.args.0.detail")
+        .should("deep.equal", {
+          consent: {
+            [PRIVACY_NOTICE_KEY_1]: false,
+            [PRIVACY_NOTICE_KEY_2]: false,
+          },
+        });
+    });
+
+    describe("when preferences are updated", () => {
+      it("emits another FidesUpdated event when reject all is clicked", () => {
+        cy.contains("button", "Reject Test").should("be.visible").click();
+        cy.get("@FidesUpdated")
+          .should("have.been.calledTwice")
+          .its("firstCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: false,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          });
+        cy.get("@FidesUpdated")
+          .its("secondCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: false,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          });
+      });
+
+      it("emits another FidesUpdated event when accept all is clicked", () => {
+        cy.contains("button", "Accept Test").should("be.visible").click();
+        cy.get("@FidesUpdated")
+          .should("have.been.calledTwice")
+          .its("firstCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: false,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          });
+        cy.get("@FidesUpdated")
+          .its("secondCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: true,
+              [PRIVACY_NOTICE_KEY_2]: true,
+            },
+          });
+      });
+
+      it("emits another FidesUpdated event when customized preferences are saved", () => {
+        cy.contains("button", "Manage preferences")
+          .should("be.visible")
+          .click();
+        cy.getByTestId("toggle-Test privacy notice").click();
+        cy.getByTestId("consent-modal").contains("Save").click();
+        cy.get("@FidesUpdated")
+          .should("have.been.calledTwice")
+          .its("firstCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: false,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          });
+        cy.get("@FidesUpdated")
+          .its("secondCall.args.0.detail")
+          .should("deep.equal", {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: true,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          });
+      });
+    });
+
+    it("pushes events to the GTM integration", () => {
+      cy.contains("button", "Accept Test").should("be.visible").click();
+      cy.get("@dataLayerPush")
+        .should("have.been.calledTwice")
+        .its("firstCall.args.0")
+        .should("deep.equal", {
+          event: "FidesInitialized",
+          Fides: {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: false,
+              [PRIVACY_NOTICE_KEY_2]: false,
+            },
+          },
+        });
+      cy.get("@dataLayerPush")
+        .its("secondCall.args.0")
+        .should("deep.equal", {
+          event: "FidesUpdated",
+          Fides: {
+            consent: {
+              [PRIVACY_NOTICE_KEY_1]: true,
+              [PRIVACY_NOTICE_KEY_2]: true,
+            },
+          },
+        });
+    });
+  });
 });