feat!: added file download tracking (#260) (#263)

* feat: added file download tracking (#260)

* feat!: made tracking parameters to azulFileDownload required (#260)

Author: Jonah Paten

src/common/analytics/entities.ts

@@ -9,6 +9,7 @@ export enum EVENT_NAME {
   ENTITY_SELECTED = "entity_selected",
   ENTITY_TABLE_PAGINATED = "entity_table_paginated",
   ENTITY_TABLE_SORTED = "entity_table_sorted",
+  FILE_DOWNLOADED = "file_downloaded",
   FILTER_SELECTED = "filter_selected",
   INDEX_ANALYZE_IN_TERRA_REQUESTED = "index_analyze_in_terra_requested",
   INDEX_FILE_MANIFEST_REQUESTED = "index_file_manifest_requested",
@@ -23,6 +24,8 @@ export enum EVENT_PARAM {
   FILTER_NAME = "filter_name",
   FILTER_VALUE = "filter_value",
   PAGINATION_DIRECTION = "pagination_direction",
+  RELATED_ENTITY_ID = "related_entity_id",
+  RELATED_ENTITY_NAME = "related_entity_name",
   SORT_DIRECTION = "sort_direction",
   TOOL_NAME = "tool_name",
 }
@@ -61,6 +64,11 @@ export type EventParams = {
     [EVENT_PARAM.COLUMN_NAME]: string;
     [EVENT_PARAM.SORT_DIRECTION]: SORT_DIRECTION;
   };
+  [EVENT_NAME.FILE_DOWNLOADED]: {
+    [EVENT_PARAM.ENTITY_NAME]: string;
+    [EVENT_PARAM.RELATED_ENTITY_ID]: string;
+    [EVENT_PARAM.RELATED_ENTITY_NAME]: string;
+  };
   [EVENT_NAME.FILTER_SELECTED]: {
     [EVENT_PARAM.FILTER_NAME]: string;
     [EVENT_PARAM.FILTER_VALUE]: string;

src/components/Export/common/tracking.ts

@@ -6,7 +6,7 @@ import { EVENT_NAME, EVENT_PARAM } from "../../../common/analytics/entities";
  * @param entity_name - Entity (tab) name.
  * @param toolName - Tool name.
  */
-export function bulkDownloadTracking(
+export function trackBulkDownloadRequested(
   entity_name: string,
   toolName: string
 ): void {
@@ -21,7 +21,7 @@ export function bulkDownloadTracking(
  * Executes event tracking for the file manifest export.
  * @param entity_name - Entity (tab) name.
  */
-export function fileManifestTracking(entity_name: string): void {
+export function trackFileManifestRequested(entity_name: string): void {
   // Track the file manifest requested event.
   track(EVENT_NAME.INDEX_FILE_MANIFEST_REQUESTED, {
     [EVENT_PARAM.ENTITY_NAME]: entity_name,
@@ -32,9 +32,28 @@ export function fileManifestTracking(entity_name: string): void {
  * Executes event tracking for the Terra export.
  * @param entity_name - Entity (tab) name.
  */
-export function exportToTerraTracking(entity_name: string): void {
+export function trackExportToTerraRequested(entity_name: string): void {
   // Track the export to terra event.
   track(EVENT_NAME.INDEX_ANALYZE_IN_TERRA_REQUESTED, {
     [EVENT_PARAM.ENTITY_NAME]: entity_name,
   });
 }
+
+/**
+ * Executes event tracking for individual file downloads
+ * @param entity_name - The name of the file downloaded.
+ * @param related_entity_id - The ID of the file's dataset / project
+ * @param related_entity_name -The name of the file's dataset / project
+ */
+export function trackFileDownloaded(
+  entity_name: string,
+  related_entity_id: string,
+  related_entity_name: string
+): void {
+  // Track the file downloaded event.
+  track(EVENT_NAME.FILE_DOWNLOADED, {
+    [EVENT_PARAM.ENTITY_NAME]: entity_name,
+    [EVENT_PARAM.RELATED_ENTITY_ID]: related_entity_id,
+    [EVENT_PARAM.RELATED_ENTITY_NAME]: related_entity_name,
+  });
+}

src/components/Export/components/DownloadCurlCommand/downloadCurlCommand.tsx

@@ -12,7 +12,7 @@ import {
   ExecutionEnvironment,
   FormFacet,
 } from "../../common/entities";
-import { bulkDownloadTracking } from "../../common/tracking";
+import { trackBulkDownloadRequested } from "../../common/tracking";
 import { DownloadCurlCommandNotStarted } from "./components/DownloadCurlCommandNotStarted/downloadCurlCommandNotStarted";
 import { DownloadCurlCommandReady } from "./components/DownloadCurlCommandReady/downloadCurlCommandReady";
 
@@ -63,7 +63,7 @@ export const DownloadCurlCommand = ({
       isLoading={isLoading}
       onRequestManifest={(): void => {
         // Execute GTM tracking.
-        bulkDownloadTracking(entityList, executionEnvironment);
+        trackBulkDownloadRequested(entityList, executionEnvironment);
         // Request manifest.
         run();
       }}

src/components/Export/components/ExportToTerra/exportToTerra.tsx

@@ -7,7 +7,7 @@ import { useFileManifest } from "../../../../hooks/useFileManifest/useFileManife
 import { useRequestFileManifest } from "../../../../hooks/useFileManifest/useRequestFileManifest";
 import { FileManifestState } from "../../../../providers/fileManifestState";
 import { FormFacet, ManifestDownloadFormat } from "../../common/entities";
-import { exportToTerraTracking } from "../../common/tracking";
+import { trackExportToTerraRequested } from "../../common/tracking";
 import { ExportToTerraNotStarted } from "./components/ExportToTerraNotStarted/exportToTerraNotStarted";
 import { ExportToTerraReady } from "./components/ExportToTerraReady/exportToTerraReady";
 
@@ -57,7 +57,7 @@ export const ExportToTerra = ({
       manifestDownloadFormats={manifestDownloadFormats}
       onRequestManifest={(): void => {
         // Execute GA tracking
-        exportToTerraTracking(entityList);
+        trackExportToTerraRequested(entityList);
         // Request manifest
         run();
       }}

src/components/Export/components/ManifestDownload/manifestDownload.tsx

@@ -8,7 +8,7 @@ import { useRequestFileManifest } from "../../../../hooks/useFileManifest/useReq
 import { FileLocation } from "../../../../hooks/useRequestFileLocation";
 import { FileManifestState } from "../../../../providers/fileManifestState";
 import { FormFacet } from "../../common/entities";
-import { fileManifestTracking } from "../../common/tracking";
+import { trackFileManifestRequested } from "../../common/tracking";
 import { ManifestDownloadNotStarted } from "./components/ManifestDownloadNotStarted/manifestDownloadNotStarted";
 import { ManifestDownloadReady } from "./components/ManifestDownloadReady/manifestDownloadReady";
 
@@ -55,7 +55,7 @@ export const ManifestDownload = ({
       formFacet={formFacet}
       isLoading={isLoading}
       onRequestManifest={(): void => {
-        fileManifestTracking(entityList);
+        trackFileManifestRequested(entityList);
         run();
       }}
     />

src/components/Index/components/AzulFileDownload/azulFileDownload.tsx

@@ -4,6 +4,7 @@ import { useFileLocation } from "../../../../hooks/useFileLocation";
 import { DownloadIcon } from "../../../common/CustomIcon/components/DownloadIcon/downloadIcon";
 import { LoadingIcon } from "../../../common/CustomIcon/components/LoadingIcon/loadingIcon";
 import { IconButton } from "../../../common/IconButton/iconButton";
+import { trackFileDownloaded } from "../../../Export/common/tracking";
 import { StyledIconButton } from "./azulFileDownload.styles";
 import {
   AZUL_FILE_DOWNLOAD_TEST_ID,
@@ -12,10 +13,16 @@ import {
 } from "./common/constants";
 
 export interface AzulFileDownloadProps {
+  entityName: string; // The name of the file downloaded.
+  relatedEntityId: string; // An array of IDs of the file's datasets / projects
+  relatedEntityName: string; // An array of names of the file's datasets / projects
   url?: string; // Original "file fetch URL" as returned from Azul endpoint.
 }
 
 export const AzulFileDownload = ({
+  entityName,
+  relatedEntityId,
+  relatedEntityName,
   url,
 }: AzulFileDownloadProps): JSX.Element => {
   const { fileUrl, isLoading, run } = useFileLocation(url);
@@ -49,6 +56,7 @@ export const AzulFileDownload = ({
           Icon={isLoading ? LoadingIcon : DownloadIcon}
           onClick={(): void => {
             setIsRequestPending(true);
+            trackFileDownloaded(entityName, relatedEntityId, relatedEntityName);
             run();
           }}
           size="medium"

tests/azulFileDownload.test.tsx

@@ -21,6 +21,11 @@ describe("AzulFileDownload", () => {
   const FILE_URL = "https://example.com/storage/file";
   const MOCK_RUN = jest.fn();
   const URL = "https://example.com/repository/file";
+  const TRACKING_PARAMETERS = {
+    entityName: "filename.extension",
+    relatedEntityId: "id",
+    relatedEntityName: "name",
+  };
   beforeEach(() => {
     (useFileLocation as jest.Mock).mockReturnValue({
       fileUrl: undefined,
@@ -33,24 +38,24 @@ describe("AzulFileDownload", () => {
   });
   describe("download button", () => {
     test("should render the download button", () => {
-      render(<AzulFileDownload url={URL} />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} url={URL} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       expect(buttonEl).not.toBeNull();
     });
     test("should disable the download button if URL is undefined", () => {
-      render(<AzulFileDownload />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       expect(buttonEl.disabled).toBe(true);
     });
     test("should enable the download button if a URL is provided", () => {
-      render(<AzulFileDownload url={URL} />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} url={URL} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       expect(buttonEl.disabled).toBe(false);
     });
   });
   describe("download functionality", () => {
     test("should call the run function when the button is clicked", () => {
-      render(<AzulFileDownload url={URL} />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} url={URL} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       fireEvent.click(buttonEl);
       expect(MOCK_RUN).toHaveBeenCalled();
@@ -61,7 +66,7 @@ describe("AzulFileDownload", () => {
         isLoading: false,
         run: MOCK_RUN,
       });
-      render(<AzulFileDownload url={URL} />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} url={URL} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       fireEvent.click(buttonEl);
       await waitFor(() => {
@@ -80,7 +85,7 @@ describe("AzulFileDownload", () => {
         isLoading: false,
         run: MOCK_RUN,
       });
-      render(<AzulFileDownload url={URL} />);
+      render(<AzulFileDownload {...TRACKING_PARAMETERS} url={URL} />);
       const buttonEl = getButtonById(AZUL_FILE_REQUEST_DOWNLOAD_TEST_ID);
       const anchorEl = getAnchorEl(AZUL_FILE_DOWNLOAD_TEST_ID);
       fireEvent.click(buttonEl);