Add onFidesEvent method for an alternative way to subscribe to Fides events

CHANGELOG.md

@@ -25,6 +25,7 @@ The types of changes are:
 - Add ability to edit dataset YAML from dataset view [#5262](https://github.com/ethyca/fides/pull/5262)
 - Added support for "in progress" status in classification [#5248](https://github.com/ethyca/fides/pull/5248)
 - Clarify GCP service account permissions when setting up Google Cloud SQL for Postgres in Admin-UI [#5245](https://github.com/ethyca/fides/pull/5266)
+- Add onFidesEvent method for an alternative way to subscribe to Fides events [#5297](https://github.com/ethyca/fides/pull/5297)
 
 ### Changed
 - Validate no path in `server_host` var for CLI config; if there is one then take only up until the first forward slash

clients/fides-js/docs/interfaces/Fides.md

@@ -280,6 +280,42 @@ such as the `fides_overrides` global or the query params.
 
 ***
 
+### onFidesEvent()
+
+> **onFidesEvent**: (`type`, `callback`) => () => `void`
+
+An alternative way to subscribe to Fides events. The same events are supported, except the callback
+receives the event details directly. This is useful in restricted environments where you can't
+directly access `window.addEventListener`.
+
+Returns an unsubscribe function that can be called to remove the event listener.
+
+#### Example
+
+```ts
+const unsubscribe = Fides.onFidesEvent("FidesUpdated", (detail) => {
+  console.log(detail.consent);
+  unsubscribe();
+});
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `type` | `any` | The type of event to listen for, such as `FidesInitialized`, `FidesUpdated`, etc. |
+| `callback` | (`detail`) => `void` | The callback function to call when the event is triggered |
+
+#### Returns
+
+`Function`
+
+##### Returns
+
+`void`
+
+***
+
 ### ~~reinitialize()~~
 
 > **reinitialize**: () => `Promise`\<`void`\>

clients/fides-js/src/docs/fides.ts

@@ -228,6 +228,26 @@ export interface Fides {
    */
   init: (config?: any) => Promise<void>;
 
+  /**
+   * An alternative way to subscribe to Fides events. The same events are supported, except the callback
+   * receives the event details directly. This is useful in restricted environments where you can't
+   * directly access `window.addEventListener`.
+   *
+   * Returns an unsubscribe function that can be called to remove the event listener.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = Fides.onFidesEvent("FidesUpdated", (detail) => {
+   *   console.log(detail.consent);
+   *   unsubscribe();
+   * });
+   * ```
+   *
+   * @param type The type of event to listen for, such as `FidesInitialized`, `FidesUpdated`, etc.
+   * @param callback The callback function to call when the event is triggered
+   */
+  onFidesEvent: (type: any, callback: (detail: any) => void) => () => void;
+
   /**
    * @deprecated
    * `Fides.init()` can now be used directly instead of `Fides.reinitialize()`.

clients/fides-js/src/fides-tcf.ts

@@ -32,7 +32,7 @@ import {
   OverrideType,
   PrivacyExperience,
 } from "./lib/consent-types";
-import { dispatchFidesEvent } from "./lib/events";
+import { dispatchFidesEvent, onFidesEvent } from "./lib/events";
 import type { GppFunction } from "./lib/gpp/types";
 import { DEFAULT_MODAL_LINK_LABEL } from "./lib/i18n";
 import {
@@ -290,6 +290,7 @@ const _Fides: FidesGlobal = {
     );
   },
   initialized: false,
+  onFidesEvent,
   meta,
   shopify,
   showModal: defaultShowModal,

clients/fides-js/src/fides.ts

@@ -29,7 +29,7 @@ import {
   consentCookieObjHasSomeConsentSet,
   updateExperienceFromCookieConsentNotices,
 } from "./lib/cookie";
-import { dispatchFidesEvent } from "./lib/events";
+import { dispatchFidesEvent, onFidesEvent } from "./lib/events";
 import { DEFAULT_MODAL_LINK_LABEL } from "./lib/i18n";
 import {
   getInitialCookie,
@@ -212,6 +212,7 @@ const _Fides: FidesGlobal = {
     return this.init();
   },
   initialized: false,
+  onFidesEvent,
   shouldShowExperience() {
     if (!isPrivacyExperience(this.experience)) {
       // Nothing to show if there's no experience

clients/fides-js/src/lib/consent-types.ts

@@ -1,7 +1,8 @@
-import type { Fides, FidesOptions } from "../docs";
+import type { Fides, FidesEventType, FidesOptions } from "../docs";
 import type { gtm } from "../integrations/gtm";
 import type { meta } from "../integrations/meta";
 import type { shopify } from "../integrations/shopify";
+import type { FidesEventDetail } from "./events";
 import type { GPPFieldMapping, GPPSettings } from "./gpp/types";
 import type {
   GVLJson,
@@ -150,6 +151,10 @@ export interface FidesGlobal extends Fides {
   gtm: typeof gtm;
   init: (config?: FidesConfig) => Promise<void>;
   meta: typeof meta;
+  onFidesEvent: (
+    type: FidesEventType,
+    callback: (evt: FidesEventDetail) => void,
+  ) => () => void;
   reinitialize: () => Promise<void>;
   shopify: typeof shopify;
   shouldShowExperience: () => boolean;

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

@@ -81,3 +81,21 @@ export const dispatchFidesEvent = (
     window.dispatchEvent(event);
   }
 };
+
+/**
+ * An alternative way to subscribe to Fides events. The same events are supported, except the callback
+ * receives the event details directly. This is useful in restricted environments where you can't
+ * directly access `window.addEventListener`.
+ *
+ * Returns an unsubscribe function that can be called to remove the event listener.
+ */
+export const onFidesEvent = (
+  type: FidesEventType,
+  callback: (evt: FidesEventDetail) => void,
+): (() => void) => {
+  const listener = (evt: FidesEvent) => callback(evt.detail);
+  window.addEventListener(type, listener);
+  return () => {
+    window.removeEventListener(type, listener);
+  };
+};