Allow Users to Pass Function to Measure-Tools Feature Tracking

packages/itwin/measure-tools/README.md

@@ -99,3 +99,60 @@ An application can further customize UI event behavior by registering override h
 
 A concrete example of this customization is an application that has measurements organized into multiple groups. One group may be "frozen" due to some application state (state that the measure-tools library may be unaware of) and should not be cleared by the clear measurements tool.
 So the application would register a custom UI event handler that would cause those measurements to be ignored when the clear measurement tool is invoked.
+
+### Usage Tracking
+
+This package allows consumers to track the usage of specific features.
+
+This can be achieved by passing `onFeatureUsed` function to `MeasureToolsUiProvider`. The function is invoked with the information about the feature being used. The feature information is based off Feature interface (that can be imported from `"@itwin/measure-tools-react"`)
+
+```
+export interface Feature {
+  name: string;
+  guid: GuidString;
+  metaData?: Map<string, any>;
+}
+```
+
+As an example, for Measure Distance, we will have
+
+```
+{
+  name: "CRT_Tools_MeasureDistance",
+  guid: "10e474ee-9af8-4262-a505-77c9d896b065",
+}
+```
+
+### Example for Usage Tracking
+
+In this case, we create a sample [Itwin Viewer](https://www.npmjs.com/package/@itwin/web-viewer-react) and configure `MeasureToolsUiProvider`
+
+```ts
+import { Feature, MeasureToolsUiItemsProvider } from "@itwin/measure-tools-react";
+
+const App: React.FC = () => {
+  // Viewer Setup here...
+  return (
+    <div className="viewer-container">
+      <Viewer
+        iTwinId={iTwinId ?? ""}
+        iModelId={iModelId ?? ""}
+        changeSetId={changesetId}
+        authClient={authClient}
+        viewCreatorOptions={viewCreatorOptions}
+        enablePerformanceMonitors={true}
+        onIModelAppInit={onIModelAppInit}
+        uiProviders={[
+          new MeasureToolsUiItemsProvider({
+            onFeatureUsed: (feature: Feature) => {
+              console.log(`MeasureTools [${feature.name}] used`);
+            },
+          }),
+        ]}
+      />
+    </div>
+  );
+};
+
+export default App;
+```

packages/itwin/measure-tools/src/ui-2.0/MeasureToolsUiProvider.tsx

@@ -17,6 +17,7 @@ import { MeasureToolDefinitions } from "../tools/MeasureToolDefinitions";
 import type { RecursiveRequired } from "../utils/types";
 import { MeasurementPropertyWidget, MeasurementPropertyWidgetId } from "./MeasurementPropertyWidget";
 import { IModelApp } from "@itwin/core-frontend";
+import { Feature, FeatureTracking } from "../measure-tools-react";
 
 // Note: measure tools cannot pick geometry when a sheet view is active to snap to and therefore must be hidden
 //  to avoid giving the user the impression they should work
@@ -32,11 +33,13 @@ export interface MeasureToolsUiProviderOptions {
   // If we check for sheet to 3d transformation when measuring in sheets
   enableSheetMeasurement?: boolean;
   stageUsageList?: string[];
+  // Callback that is invoked when a tracked feature is used.
+  onFeatureUsed?: (feature: Feature) => void;
 }
 
 export class MeasureToolsUiItemsProvider implements UiItemsProvider {
   public readonly id = "MeasureToolsUiItemsProvider";
-  private _props: RecursiveRequired<MeasureToolsUiProviderOptions>;
+  private _props: Omit<RecursiveRequired<MeasureToolsUiProviderOptions>, 'onFeatureUsed'>;
 
   constructor(props?: MeasureToolsUiProviderOptions) {
     this._props = {
@@ -49,6 +52,8 @@ export class MeasureToolsUiItemsProvider implements UiItemsProvider {
       enableSheetMeasurement: props?.enableSheetMeasurement ?? false,
       stageUsageList: props?.stageUsageList ?? [StageUsage.General],
     };
+    if (!FeatureTracking.onFeature.numberOfListeners && props?.onFeatureUsed)
+      FeatureTracking.onFeature.addListener(props?.onFeatureUsed);
   }
 
   public provideToolbarItems(