LJ 464: Update all FidesJS events with timestamp, and all FidesUIChanged events with extraDetails.trigger and extraDetails.preference (#5859)

Author: NevilleS

CHANGELOG.md

@@ -42,8 +42,11 @@ Changes can also be flagged with a GitHub label for tracking purposes. The URL o
 ## [2.56.2](https://github.com/ethyca/fides/compare/2.56.1...2.56.2)
 
 ### Added
-- Fides GTM & event origination [#5821](https://github.com/ethyca/fides/pull/5821)
+- Update FidesJS to push all `FidesEvent` types to GTM (except `FidesInitializing`) [#5821](https://github.com/ethyca/fides/pull/5821)
 - Added a consent reporting table and consent lookup feature [#5839](https://github.com/ethyca/fides/pull/5839)
+- Added a high-precision `timestamp` to all `FidesEvents` from FidesJS SDK [#5859](https://github.com/ethyca/fides/pull/5859)
+- Added a `extraDetails.trigger` to `FidesUIChanged` events from FidesJS SDK with info about the UI element that triggered the event [#5859](https://github.com/ethyca/fides/pull/5859)
+- Added a `extraDetails.preference` to `FidesUIChanged` events from FidesJS SDK with info about the preference that was changed (notice, TCF purpose, TCF vendor, etc.) [#5859](https://github.com/ethyca/fides/pull/5859)
 
 ### Fixed
 - Addressed TCModel console error when opting into some purposes [#5850](https://github.com/ethyca/fides/pull/5850)

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

@@ -94,6 +94,15 @@ User's current consent preferences; see [Fides.consent](Fides.md#consent) for de
 
 User's current consent string; see [Fides.fides_string](Fides.md#fides_string) for detail.
 
+#### timestamp?
+
+> `optional` **timestamp**: `number`
+
+High-precision timestamp from [performance.mark()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark)
+representing when this event was created. The timestamp is measured in milliseconds since page load.
+
+May be undefined if the Performance API is not available.
+
 #### extraDetails?
 
 > `optional` **extraDetails**: `object`
@@ -118,23 +127,100 @@ Whether the user should be shown the consent experience. Only available on Fides
 
 What consent method (if any) caused this event.
 
-#### extraDetails.servingToggle?
+#### extraDetails.trigger?
+
+> `optional` **trigger**: `object`
+
+What UI element (if any) triggered this event.
+
+#### extraDetails.trigger.type
+
+> **type**: `"toggle"`
+
+The type of element that triggered the event. Additional types may be
+added over time (e.g. "button", "link"), so expect this type to grow.
+
+#### extraDetails.trigger.label?
+
+> `optional` **label**: `string`
+
+The UI label of the element that triggered the event.
+
+#### extraDetails.trigger.checked?
+
+> `optional` **checked**: `boolean`
+
+The checked state of the element that triggered the event.
+Only present when type is "toggle".
+
+#### extraDetails.preference?
+
+> `optional` **preference**: `object`
+
+Information about the specific preference being changed, if this event
+was triggered by a preference change.
+
+##### Example
+
+```ts
+// For a notice toggle:
+preference: {
+  key: "advertising",
+  type: "notice"
+}
+
+// For a TCF purpose toggle:
+preference: {
+  key: "tcf_purpose_consent_4",
+  type: "tcf_purpose_consent"
+}
+
+// For a TCF vendor toggle:
+preference: {
+  key: "gvl.2",
+  type: "tcf_vendor_consent",
+  vendor_id: "gvl.2",
+  vendor_list: "gvl",
+  vendor_list_id: "2",
+  vendor_name: "Captify"
+}
+```
+
+#### extraDetails.preference.key
+
+> **key**: `string`
+
+The unique key identifying this preference
+
+#### extraDetails.preference.type
+
+> **type**: `"notice"` \| `"tcf_purpose_consent"` \| `"tcf_purpose_legitimate_interest"` \| `"tcf_special_feature"` \| `"tcf_vendor_consent"` \| `"tcf_vendor_legitimate_interest"`
+
+The type of preference being changed
+
+#### extraDetails.preference.vendor\_id?
+
+> `optional` **vendor\_id**: `string`
+
+The vendor ID if this is a vendor-related preference
+
+#### extraDetails.preference.vendor\_list?
 
-> `optional` **servingToggle**: `object`
+> `optional` **vendor\_list**: `"gvl"` \| `"gacp"` \| `"fds"`
 
-What toggle (if any) caused this event.
+The vendor list type if this is a vendor-related preference
 
-#### extraDetails.servingToggle.label
+#### extraDetails.preference.vendor\_list\_id?
 
-> **label**: `string`
+> `optional` **vendor\_list\_id**: `string`
 
-#### extraDetails.servingToggle.id
+The vendor list ID if this is a vendor-related preference
 
-> **id**: `string`
+#### extraDetails.preference.vendor\_name?
 
-#### extraDetails.servingToggle.checked
+> `optional` **vendor\_name**: `string`
 
-> **checked**: `boolean`
+The vendor name if this is a vendor-related preference
 
 #### Overrides
 

clients/fides-js/package.json

@@ -73,7 +73,7 @@
     "rollup-plugin-postcss": "^4.0.2",
     "rollup-plugin-visualizer": "^5.12.0",
     "ts-jest": "^29.1.5",
-    "typedoc": "^0.26.2",
+    "typedoc": "^0.26.11",
     "typedoc-plugin-markdown": "^4.1.0",
     "typescript": "^4.9.5",
     "typescript-plugin-css-modules": "^5.0.1"

clients/fides-js/src/components/DataUseToggle.tsx

@@ -1,6 +1,6 @@
 import { ComponentChildren, h, VNode } from "preact";
 
-import { FidesServingToggleDetails } from "../lib/events";
+import { FidesEventDetailsTrigger } from "../lib/events";
 import { useDisclosure } from "../lib/hooks";
 import Toggle from "./Toggle";
 
@@ -23,7 +23,7 @@ const DataUseToggle = ({
   checked: boolean;
   onToggle: (
     noticeKey: string,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
   ) => void;
   children?: ComponentChildren;
   badge?: string;

clients/fides-js/src/components/Toggle.tsx

@@ -1,6 +1,6 @@
 import { h } from "preact";
 
-import { FidesServingToggleDetails } from "../lib/events";
+import { FidesEventDetailsTrigger } from "../lib/events";
 
 const Toggle = ({
   label,
@@ -18,7 +18,7 @@ const Toggle = ({
   checked: boolean;
   onChange: (
     noticeKey: string,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
   ) => void;
   disabled?: boolean;
   onLabel?: string;
@@ -33,8 +33,11 @@ const Toggle = ({
         aria-label={label}
         className="fides-toggle-input"
         onChange={() => {
-          const nextCheckedState = !checked;
-          onChange(id, { id, label, checked: nextCheckedState });
+          onChange(id, {
+            type: "toggle",
+            label,
+            checked: !checked,
+          });
         }}
         checked={checked}
         role="switch"

clients/fides-js/src/components/notices/NoticeOverlay.tsx

@@ -361,11 +361,12 @@ const NoticeOverlay: FunctionComponent<OverlayProps> = ({
             <NoticeToggles
               noticeToggles={noticeToggles}
               enabledNoticeKeys={draftEnabledNoticeKeys}
-              onChange={(updatedKeys, toggleDetails) => {
+              onChange={(updatedKeys, triggerDetails, preference) => {
                 const eventExtraDetails: FidesEvent["detail"]["extraDetails"] =
                   {
                     servingComponent: "modal",
-                    servingToggle: toggleDetails,
+                    trigger: triggerDetails,
+                    preference,
                   };
                 setDraftEnabledNoticeKeys(updatedKeys);
                 dispatchFidesEvent(

clients/fides-js/src/components/notices/NoticeToggles.tsx

@@ -1,7 +1,10 @@
 import { h } from "preact";
 
 import { GpcStatus } from "../../lib/consent-types";
-import { FidesServingToggleDetails } from "../../lib/events";
+import {
+  FidesEventDetailsPreference,
+  FidesEventDetailsTrigger,
+} from "../../lib/events";
 import { DEFAULT_LOCALE, getCurrentLocale } from "../../lib/i18n";
 import { useI18n } from "../../lib/i18n/i18n-context";
 import DataUseToggle from "../DataUseToggle";
@@ -26,23 +29,34 @@ export const NoticeToggles = ({
   enabledNoticeKeys: Array<string>;
   onChange: (
     keys: Array<string>,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
+    preferenceDetails: FidesEventDetailsPreference,
   ) => void;
 }) => {
   const { i18n } = useI18n();
   const handleToggle = (
     noticeKey: string,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
   ) => {
+    const preferenceDetails: FidesEventDetailsPreference = {
+      key: noticeKey,
+      type: "notice",
+    };
+
     // Add the notice to list of enabled notices
     if (enabledNoticeKeys.indexOf(noticeKey) === -1) {
-      onChange([...enabledNoticeKeys, noticeKey], toggleDetails);
+      onChange(
+        [...enabledNoticeKeys, noticeKey],
+        triggerDetails,
+        preferenceDetails,
+      );
     }
     // Remove the notice from the list of enabled notices
     else {
       onChange(
         enabledNoticeKeys.filter((n) => n !== noticeKey),
-        toggleDetails,
+        triggerDetails,
+        preferenceDetails,
       );
     }
   };

clients/fides-js/src/components/tcf/RecordsList.tsx

@@ -1,7 +1,7 @@
 import { h, VNode } from "preact";
 
 import { PrivacyNoticeTranslation } from "../../lib/consent-types";
-import { FidesServingToggleDetails } from "../../lib/events";
+import { FidesEventDetailsTrigger } from "../../lib/events";
 import { DEFAULT_LOCALE, getCurrentLocale } from "../../lib/i18n";
 import { useI18n } from "../../lib/i18n/i18n-context";
 import DataUseToggle from "../DataUseToggle";
@@ -29,7 +29,7 @@ interface Props<T extends RecordListItem> {
   onToggle: (
     payload: string[],
     item: T,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
   ) => void;
   renderBadgeLabel?: (item: T) => string | undefined;
   hideToggles?: boolean;
@@ -50,16 +50,16 @@ const RecordsList = <T extends RecordListItem>({
     return null;
   }
 
-  const handleToggle = (item: T, toggleDetails: FidesServingToggleDetails) => {
+  const handleToggle = (item: T, triggerDetails: FidesEventDetailsTrigger) => {
     const purposeId = `${item.id}`;
     if (enabledIds.indexOf(purposeId) !== -1) {
       onToggle(
         enabledIds.filter((e) => e !== purposeId),
         item,
-        toggleDetails,
+        triggerDetails,
       );
     } else {
-      onToggle([...enabledIds, purposeId], item, toggleDetails);
+      onToggle([...enabledIds, purposeId], item, triggerDetails);
     }
   };
 
@@ -88,8 +88,8 @@ const RecordsList = <T extends RecordListItem>({
           key={item.id}
           title={item.bestTranslation?.title || getNameForItem(item)}
           noticeKey={`${item.id}`}
-          onToggle={(_, extraDetails) => {
-            handleToggle(item, extraDetails);
+          onToggle={(_, triggerDetails) => {
+            handleToggle(item, triggerDetails);
           }}
           checked={enabledIds.indexOf(`${item.id}`) !== -1}
           badge={renderBadgeLabel ? renderBadgeLabel(item) : undefined}

clients/fides-js/src/components/tcf/TcfFeatures.tsx

@@ -1,7 +1,10 @@
 import { h } from "preact";
 
 import { PrivacyExperience } from "../../lib/consent-types";
-import { FidesServingToggleDetails } from "../../lib/events";
+import {
+  FidesEventDetailsPreference,
+  FidesEventDetailsTrigger,
+} from "../../lib/events";
 import { useI18n } from "../../lib/i18n/i18n-context";
 import { TCFFeatureRecord, TCFSpecialFeatureRecord } from "../../lib/tcf/types";
 import EmbeddedVendorList from "./EmbeddedVendorList";
@@ -40,7 +43,8 @@ const TcfFeatures = ({
   enabledSpecialFeatureIds: string[];
   onChange: (
     payload: UpdateEnabledIds,
-    toggleDetails: FidesServingToggleDetails,
+    triggerDetails: FidesEventDetailsTrigger,
+    preferenceDetails: FidesEventDetailsPreference,
   ) => void;
 }) => {
   const { i18n } = useI18n();
@@ -51,9 +55,11 @@ const TcfFeatures = ({
         title={i18n.t("static.tcf.features")}
         items={allFeatures ?? []}
         enabledIds={enabledFeatureIds}
-        onToggle={(newEnabledIds, _, toggleDetails) =>
-          onChange({ newEnabledIds, modelType: "features" }, toggleDetails)
-        }
+        onToggle={() => {
+          // Regular features cannot be toggled - they are notice-only.
+          // The hideToggles prop ensures the UI doesn't show toggle controls,
+          // and this no-op handler ensures no events are fired even if somehow triggered.
+        }}
         renderToggleChild={(f) => (
           <FeatureChildren type="features" feature={f} />
         )}
@@ -64,10 +70,14 @@ const TcfFeatures = ({
         title={i18n.t("static.tcf.special_features")}
         items={allSpecialFeatures ?? []}
         enabledIds={enabledSpecialFeatureIds}
-        onToggle={(newEnabledIds, _, toggleDetails) =>
+        onToggle={(newEnabledIds, item, triggerDetails) =>
           onChange(
             { newEnabledIds, modelType: "specialFeatures" },
-            toggleDetails,
+            triggerDetails,
+            {
+              key: `tcf_special_feature_${item.id}`,
+              type: "tcf_special_feature",
+            },
           )
         }
         renderToggleChild={(f) => (

clients/fides-js/src/components/tcf/TcfOverlay.tsx

@@ -560,9 +560,13 @@ export const TcfOverlay = ({
                 experience={experience}
                 customNotices={privacyNoticesWithBestTranslation}
                 enabledIds={draftIds}
-                onChange={(updatedIds, toggleDetails) => {
+                onChange={(updatedIds, triggerDetails, preference) => {
                   const eventExtraDetails: FidesEvent["detail"]["extraDetails"] =
-                    { servingComponent: "modal", servingToggle: toggleDetails };
+                    {
+                      servingComponent: "modal",
+                      trigger: triggerDetails,
+                      preference,
+                    };
                   setDraftIds(updatedIds);
                   dispatchFidesEvent(
                     "FidesUIChanged",