Feature Usage Tracking Callbacks (#110)

Add tracking for changed elements UI operations. Update gitignore.

.gitignore

@@ -7,3 +7,5 @@ npm-debug.log*
 pnpm-debug.log*
 
 .env.*
+
+packages/test-app-frontend/dist/

packages/changed-elements-react/src/api/VersionCompare.ts

@@ -13,8 +13,18 @@ import { ChangedElementsClientBase } from "./ChangedElementsClientBase.js";
 import { VersionCompareManager } from "./VersionCompareManager.js";
 import { VisualizationHandler } from "./VisualizationHandler.js";
 
+/** Feature usage tracking callbacks for changed elements UI operations */
 export interface VersionCompareFeatureTracking {
-  trackInspectElementTool: () => void;
+  /** Track when the user opens the version compare selector dialog to start a comparison using V2 API */
+  trackVersionSelectorV2Usage: () => void;
+  /** Track when the user opens the version compare selector dialog to start a comparison */
+  trackVersionSelectorUsage: () => void;
+  /** Tracks when the user does a property comparison and opens the side-by-side frontstage */
+  trackPropertyComparisonUsage: () => void;
+  /** Tracks when the user opens the change report dialog */
+  trackChangeReportGenerationUsage: () => void;
+  /** Tracks when the user opens the advanced filter dialog */
+  trackAdvancedFiltersUsage: () => void;
 }
 
 /**

packages/changed-elements-react/src/api/VersionCompareManager.ts

@@ -71,10 +71,8 @@ export class VersionCompareManager {
     return this._visualizationHandler;
   }
 
-  public get featureTracking(): VersionCompareFeatureTracking {
-    return this.options.featureTracking !== undefined
-      ? this.options.featureTracking
-      : { trackInspectElementTool: () => ({}) };
+  public get featureTracking(): VersionCompareFeatureTracking | undefined {
+    return this.options.featureTracking;
   }
 
   public get filterSpatial(): boolean {
@@ -345,6 +343,7 @@ export class VersionCompareManager {
       // Raise event
       this.versionCompareStarted.raiseEvent(this._currentIModel, this._targetIModel, changedElementEntries);
       VersionCompareUtils.outputVerbose(VersionCompareVerboseMessages.versionCompareManagerStartedComparison);
+      VersionCompare.manager?.featureTracking?.trackVersionSelectorUsage();
     } catch (ex) {
       // Let user know comparison failed - TODO: Give better errors
       const briefError = IModelApp.localization.getLocalizedString(
@@ -475,6 +474,7 @@ export class VersionCompareManager {
       // Raise event
       this.versionCompareStarted.raiseEvent(this._currentIModel, this._targetIModel, changedElementEntries);
       VersionCompareUtils.outputVerbose(VersionCompareVerboseMessages.versionCompareManagerStartedComparison);
+      VersionCompare.manager?.featureTracking?.trackVersionSelectorV2Usage();
     } catch (ex) {
       // Let user know comparison failed - TODO: Give better errors
       const briefError = IModelApp.localization.getLocalizedString(
@@ -563,6 +563,7 @@ export class VersionCompareManager {
    * Initialize property comparison using the visualization handler
    */
   public async initializePropertyComparison(): Promise<void> {
+    VersionCompare.manager?.featureTracking?.trackPropertyComparisonUsage();
     await this._visualizationHandler?.startPropertyComparison();
   }
 }

packages/changed-elements-react/src/widgets/ChangedElementsWidget.tsx

@@ -258,7 +258,6 @@ export class ChangedElementsWidget extends Component<ChangedElementsWidgetProps,
 
   /** Go into property comparison. */
   private _handleInspect = async (): Promise<void> => {
-    this.state.manager.featureTracking.trackInspectElementTool();
     await this.state.manager.initializePropertyComparison();
     VersionCompareUtils.outputVerbose(VersionCompareVerboseMessages.comparisonLegendWidgetInitializeInspect);
   };
@@ -301,6 +300,7 @@ export class ChangedElementsWidget extends Component<ChangedElementsWidgetProps,
       }));
     }
 
+    VersionCompare.manager?.featureTracking?.trackChangeReportGenerationUsage();
     this.openReportDialog(properties.length > 0 ? properties : undefined);
   };
 

packages/changed-elements-react/src/widgets/EnhancedElementsInspector.tsx

@@ -222,6 +222,7 @@ function ChangeTypeFilterHeader(props: FilterHeaderProps): ReactElement {
 
   /** Handle opening the advanced filter property dialog. */
   const openAdvancedFilterDialog = async () => {
+    VersionCompare.manager?.featureTracking?.trackAdvancedFiltersUsage();
     try {
       if (props.onLoadLabels) {
         props.onLoadLabels(false);
@@ -1251,7 +1252,6 @@ export class ChangedElementsListComponent extends Component<ChangedElementsListP
 
   private _onPropertyCompare = async (): Promise<void> => {
     this.saveState();
-    this.props.manager.featureTracking.trackInspectElementTool();
     await this.props.manager.initializePropertyComparison();
     VersionCompareUtils.outputVerbose(VersionCompareVerboseMessages.comparisonLegendWidgetInitializeInspect);
   };

packages/test-app-frontend/src/App/ITwinJsApp/ITwinJsApp.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 /*---------------------------------------------------------------------------------------------
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
@@ -8,7 +9,8 @@ import {
   UiItemsProvider, type Widget
 } from "@itwin/appui-react";
 import {
-  ChangedElementsWidget, ComparisonJobClient, ITwinIModelsClient, VersionCompare, VersionCompareContext
+  ChangedElementsWidget, ComparisonJobClient, ITwinIModelsClient, VersionCompare, VersionCompareContext,
+  VersionCompareFeatureTracking
 } from "@itwin/changed-elements-react";
 import { Id64 } from "@itwin/core-bentley";
 import {
@@ -125,6 +127,15 @@ export function ITwinJsApp(props: ITwinJsAppProps): ReactElement | null {
 
 const savedFilters = new MockSavedFiltersManager();
 
+/** Simple console log testing functions for feature tracking implementation */
+const featureTrackingTesterFunctions: VersionCompareFeatureTracking = {
+  trackVersionSelectorV2Usage: () => { console.log("trackVersionSelectorV2Usage"); },
+  trackVersionSelectorUsage: () => { console.log("trackVersionSelectorUsage"); },
+  trackPropertyComparisonUsage: () => { console.log("trackPropertyComparisonUsage"); },
+  trackChangeReportGenerationUsage: () => { console.log("trackChangeReportGenerationUsage"); },
+  trackAdvancedFiltersUsage: () => { console.log("trackAdvancedFiltersUsage"); },
+}
+
 export async function initializeITwinJsApp(authorizationClient: AuthorizationClient): Promise<void> {
   if (IModelApp.initialized) {
     return;
@@ -165,6 +176,7 @@ export async function initializeITwinJsApp(authorizationClient: AuthorizationCli
       manager,
       { frontstageIds: [MainFrontstageProvider.name] },
     ),
+    featureTracking: featureTrackingTesterFunctions,
   });
 
   ReducerRegistryInstance.registerReducer("versionCompareState", VersionCompareReducer);