@cognite/reveal-widget 0.2.0 → 0.3.0

package/README.md

@@ -9,6 +9,40 @@ This package exposes `RevealWidget` and the types needed to drive it via
 `RevealWidgetController`. More capabilities from the broader Reveal Components toolkit
 will be exposed here incrementally over time.
 
+## Usage tracking (Mixpanel)
+
+`RevealWidget` can report anonymous usage events to a Cognite-owned Mixpanel project. This
+tells us which features of the widget are actually used (loading a resource, styling
+instances, moving the camera, etc.) so we can prioritize development. No event payload
+includes page URLs, referrers, resource IDs, or any other identifying data.
+
+`RevealWidget` requires an `appIdentifier` prop so aggregate usage can be attributed
+correctly. The optional `tracking` prop lets you change where events go:
+
+```tsx
+// Reports to the default Cognite Mixpanel project (the default when `tracking` is omitted).
+<RevealWidget viewerOptions={...} appIdentifier="my-app" />
+
+// Opt out entirely — no events are sent anywhere.
+<RevealWidget viewerOptions={...} appIdentifier="my-app" tracking={{ disabled: true }} />
+
+// Report to your own Mixpanel project instead of Cognite's.
+<RevealWidget
+  viewerOptions={...}
+  appIdentifier="my-app"
+  tracking={{ mixpanelToken: 'your-own-project-token' }}
+/>
+
+// Route events through your own tracking/analytics pipeline instead of Mixpanel.
+<RevealWidget
+  viewerOptions={...}
+  appIdentifier="my-app"
+  tracking={{ usageMetricsTracker: { track: (event, properties) => myOwnTracker(event, properties) } }}
+/>
+```
+
+See `RevealWidgetTrackingProps` for the full set of options.
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -3,22 +3,21 @@ import { CameraState, Cognite3DViewerOptions, NodeAppearance } from '@cognite/re
 import { DmsUniqueIdentifier, ExternalId, Space } from '@cognite/reveal-components/data-providers';
 import { AssetId } from '@cognite/reveal-components/data-providers/cache';
 import { AddReveal3DResource, AllResourceIdentifier, BaseAddOptions, CadAddOptions, NewCadModelStyling as CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, PointCloudAddOptions, PointCloudResourceIdentifier, SceneAddOptions, SceneResourceIdentifier, ThreeDResourceIdentifier } from '@cognite/reveal-components/data-providers/types';
-import { InstanceId } from '@cognite/reveal-components/utilities';
+import { RevealWidgetTrackingProps } from '@cognite/reveal-components/ui/components';
+import { InstanceId, UsageMetricsTracker } from '@cognite/reveal-components/utilities';
 import { InstanceStylingGroup } from '@cognite/reveal-components/utilities/modelIds';
 import { TreeIndexStylingGroup } from '@cognite/reveal-components/utilities/styling';
-export type { AddReveal3DResource, AllResourceIdentifier, AssetId, BaseAddOptions, CadAddOptions, CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, DmsUniqueIdentifier, ExternalId, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, InstanceId, InstanceStylingGroup, PointCloudAddOptions, PointCloudResourceIdentifier, SceneAddOptions, SceneResourceIdentifier, Space, ThreeDResourceIdentifier, TreeIndexStylingGroup, };
+export type { AddReveal3DResource, AllResourceIdentifier, AssetId, BaseAddOptions, CadAddOptions, CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, DmsUniqueIdentifier, ExternalId, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, InstanceId, InstanceStylingGroup, UsageMetricsTracker, PointCloudAddOptions, PointCloudResourceIdentifier, RevealWidgetTrackingProps, SceneAddOptions, SceneResourceIdentifier, Space, ThreeDResourceIdentifier, TreeIndexStylingGroup, };
 /**
  * Public API surface for the standalone `@cognite/reveal-widget` npm package.
  *
  * `RevealWidget` here is the real, unmodified implementation from
  * `@cognite/reveal-components` — there is no runtime wrapper. `@cognite/reveal-components`
- * is a `dependencies` entry (not `devDependencies`), so it and its own published
- * dependencies (`@cognite/signal-utils`, `@cognite/underscore`) are treated as external
- * and resolved as real npm imports rather than bundled into this package's output. The
- * resource/identifier types above are re-exported directly from
- * `@cognite/reveal-components`'s narrow, already-subpath-exported type barrels
- * (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an external
- * consumer resolves normally since that package is published.
+ * is a `dependencies` entry, so it and its own published dependencies (`@cognite/signal-utils`,
+ * `@cognite/underscore`) are treated as external. The resource/identifier types above are
+ * re-exported directly from `@cognite/reveal-components`'s narrow, already-subpath-exported
+ * type barrels (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an
+ * external consumer resolves normally since that package is published.
  *
  * `Reveal3DResourceHandle`, `RevealWidgetController`, `RevealWidgetCameraController`, and
  * `RevealWidgetProps` below are still hand-declared, because their real counterparts (only
@@ -27,6 +26,16 @@ export type { AddReveal3DResource, AllResourceIdentifier, AssetId, BaseAddOption
  * and not meaningful for an external consumer anyway. `src/index.test.ts` has compile-time-only
  * (`// @ts-expect-error`-driven) tests asserting these hand-written types stay structurally
  * compatible with the real implementation — update both together when the real API changes.
+ * `RevealWidgetTrackingProps` (and its arms) don't have this problem — they only reference
+ * `UsageMetricsTracker`, so they're imported and re-exported directly from `./ui/components`
+ * rather than hand-declared.
+ *
+ * `tracking`/`appIdentifier` (on `RevealWidgetProps`) plumb through to the real `RevealWidget`'s
+ * usage-tracking seam, which reports to a dedicated, named `mixpanel-browser` instance *by
+ * default* — not Fusion's own `@cognite/metrics`/Mixpanel setup, since `@cognite/reveal-widget`
+ * is also consumed outside this monorepo. Pass `tracking: { disabled: true }` to opt out
+ * entirely, or `tracking: { mixpanelToken }` (with `appIdentifier`) to report to your own
+ * Mixpanel project instead.
  */
 export declare const Default3DStyles: {
     Highlighted: {
@@ -112,5 +121,12 @@ export type RevealWidgetProps = {
      * The widget calls this with `undefined` when the component unmounts or this callback changes
      */
     setControllerRef?: (controller: RevealWidgetController | undefined) => void;
+    /**
+     * Reports which application is using the widget and which of its features are being triggered
+     * (e.g. adding a resource, moving the camera). See `RevealWidgetTrackingProps` for the options.
+     */
+    tracking?: RevealWidgetTrackingProps;
+    /** Identifies the host application */
+    appIdentifier: string;
 };
 export declare const RevealWidget: (props: PropsWithChildren<RevealWidgetProps>) => ReactElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cognite/reveal-widget",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,7 +24,7 @@
     "ml-matrix": "^6.12.1",
     "random-seed": "^0.3.0",
     "three": "0.184.0",
-    "@cognite/reveal-components": "1.0.1",
+    "@cognite/reveal-components": "1.0.2",
     "@cognite/aura": "0.3.5"
   },
   "devDependencies": {