ENG-1940 add per install roam extension version telemetry (#1151)

* Update cache control max age in deploy script from 1 day to 60 seconds for improved caching behavior

* Enhance loading toast to display version information with date. Integrate version retrieval from utility function for improved user feedback during development.

* Refactor PostHog integration to enhance telemetry data collection. Introduced a utility for local storage access and streamlined session telemetry registration with version metadata, improving overall analytics accuracy.

* .

Author: mdroidian

apps/roam/src/index.ts

@@ -47,6 +47,7 @@ import {
 } from "./components/settings/utils/settingsEmitter";
 import { mountLeftSidebar } from "./components/LeftSidebarView";
 import { initDockedSearchSidebarPersistence } from "~/components/AdvancedNodeSearchDialog/mountAdvancedSearchInSidebar";
+import { getVersionWithDate } from "./utils/getVersion";
 
 export const DEFAULT_CANVAS_PAGE_FORMAT = "Canvas/*";
 
@@ -74,9 +75,10 @@ export default runExtension(async (onloadArgs) => {
   }
 
   if (process.env.NODE_ENV === "development") {
+    const { version } = getVersionWithDate();
     renderToast({
       id: "discourse-graph-loaded",
-      content: "Successfully loaded",
+      content: `Successfully loaded v${version}`,
       intent: "success",
       timeout: 500,
     });

apps/roam/src/utils/__tests__/extensionTelemetry.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildExtensionTelemetryProperties,
+  getOrCreateExtensionInstallId,
+} from "~/utils/extensionTelemetry";
+import type { VersionMetadata } from "~/utils/getVersion";
+
+const createStorage = (values = new Map<string, string>()) => ({
+  getItem: (key: string): string | null => values.get(key) || null,
+  setItem: (key: string, value: string): void => {
+    values.set(key, value);
+  },
+});
+
+const versionMetadata: VersionMetadata = {
+  version: "0.21.0",
+  buildDate: "2026-06-22",
+  buildCommit: "1234567890abcdef",
+  buildBranch: "main",
+  versionStamp: "0.21.0-2026-06-22-12345678",
+};
+
+describe("getOrCreateExtensionInstallId", () => {
+  it("reuses an existing install ID from storage", () => {
+    const storage = {
+      getItem: (): string => " install-id-1 ",
+      setItem: (): void => {
+        throw new Error("setItem should not be called");
+      },
+    };
+
+    expect(
+      getOrCreateExtensionInstallId({
+        storage,
+        createId: () => "new-id",
+      }),
+    ).toBe("install-id-1");
+  });
+
+  it("creates and persists an install ID when storage is empty", () => {
+    const values = new Map<string, string>();
+    const storage = createStorage(values);
+
+    expect(
+      getOrCreateExtensionInstallId({
+        storage,
+        createId: () => "new-id",
+      }),
+    ).toBe("new-id");
+    expect([...values.values()]).toEqual(["new-id"]);
+    expect(
+      getOrCreateExtensionInstallId({
+        storage,
+        createId: () => "second-id",
+      }),
+    ).toBe("new-id");
+  });
+
+  it("falls back to a runtime ID when storage throws", () => {
+    const storage = {
+      getItem: (): string => {
+        throw new Error("storage blocked");
+      },
+      setItem: (): void => undefined,
+    };
+
+    expect(
+      getOrCreateExtensionInstallId({
+        storage,
+        createId: () => "runtime-id",
+      }),
+    ).toBe("runtime-id");
+  });
+
+  it("returns the generated ID when storage cannot persist it", () => {
+    let calls = 0;
+    const storage = {
+      getItem: (): null => null,
+      setItem: (): void => {
+        throw new Error("storage blocked");
+      },
+    };
+
+    expect(
+      getOrCreateExtensionInstallId({
+        storage,
+        createId: () => {
+          calls += 1;
+          return `runtime-id-${calls}`;
+        },
+      }),
+    ).toBe("runtime-id-1");
+  });
+});
+
+describe("buildExtensionTelemetryProperties", () => {
+  it("builds direct event and session metadata with install metadata", () => {
+    expect(
+      buildExtensionTelemetryProperties({
+        versionMetadata,
+        storage: null,
+        createInstallId: () => "install-id-1",
+      }),
+    ).toEqual({
+      ...versionMetadata,
+      extensionInstallId: "install-id-1",
+    });
+  });
+
+  it("normalizes missing version fields", () => {
+    expect(
+      buildExtensionTelemetryProperties({
+        versionMetadata: {
+          version: "",
+          buildDate: " ",
+          buildCommit: "-",
+          buildBranch: "main",
+          versionStamp: "0.21.0-2026-06-22",
+        },
+        storage: null,
+        createInstallId: () => "install-id-1",
+      }),
+    ).toEqual({
+      version: "-",
+      buildDate: "-",
+      buildCommit: "-",
+      buildBranch: "main",
+      versionStamp: "0.21.0-2026-06-22",
+      extensionInstallId: "install-id-1",
+    });
+  });
+});

apps/roam/src/utils/extensionTelemetry.ts

@@ -0,0 +1,68 @@
+import type { VersionMetadata } from "./getVersion";
+
+export type ExtensionTelemetryProperties = VersionMetadata & {
+  extensionInstallId: string;
+};
+
+type StorageLike = {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+};
+
+const INSTALL_ID_STORAGE_KEY = "discourse-graphs:roam:extension-install-id";
+const FALLBACK_VALUE = "-";
+
+const hasTelemetryValue = (value: string | undefined | null): value is string =>
+  Boolean(value?.trim() && value.trim() !== FALLBACK_VALUE);
+
+const createRuntimeId = (): string => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function")
+    return crypto.randomUUID();
+
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+};
+
+const normalizeTelemetryValue = (value: string | undefined | null): string =>
+  hasTelemetryValue(value) ? value.trim() : FALLBACK_VALUE;
+
+export const getOrCreateExtensionInstallId = ({
+  storage,
+  createId = createRuntimeId,
+}: {
+  storage?: StorageLike | null;
+  createId?: () => string;
+} = {}): string => {
+  if (!storage) return createId();
+
+  let installId: string | undefined;
+  try {
+    const existingId = storage.getItem(INSTALL_ID_STORAGE_KEY);
+    if (hasTelemetryValue(existingId)) return existingId.trim();
+
+    installId = createId();
+    storage.setItem(INSTALL_ID_STORAGE_KEY, installId);
+    return installId;
+  } catch {
+    return installId || createId();
+  }
+};
+
+export const buildExtensionTelemetryProperties = ({
+  versionMetadata,
+  storage,
+  createInstallId,
+}: {
+  versionMetadata: VersionMetadata;
+  storage?: StorageLike | null;
+  createInstallId?: () => string;
+}): ExtensionTelemetryProperties => ({
+  version: normalizeTelemetryValue(versionMetadata.version),
+  buildDate: normalizeTelemetryValue(versionMetadata.buildDate),
+  buildCommit: normalizeTelemetryValue(versionMetadata.buildCommit),
+  buildBranch: normalizeTelemetryValue(versionMetadata.buildBranch),
+  versionStamp: normalizeTelemetryValue(versionMetadata.versionStamp),
+  extensionInstallId: getOrCreateExtensionInstallId({
+    storage,
+    createId: createInstallId,
+  }),
+});

apps/roam/src/utils/posthog.ts

@@ -1,9 +1,18 @@
 import { getVersionWithDate } from "./getVersion";
+import { buildExtensionTelemetryProperties } from "./extensionTelemetry";
 import posthog from "posthog-js";
 import type { CaptureResult } from "posthog-js";
 
 let initialized = false;
 
+const getLocalStorage = (): Storage | undefined => {
+  try {
+    return window.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
 export const initPostHog = (): void => {
   if (initialized) return;
   if (window.roamAlphaAPI.graph.isEncrypted) return;
@@ -38,20 +47,19 @@ export const initPostHog = (): void => {
       return result;
     },
     loaded: (posthog) => {
-      const { version, buildDate, buildCommit, buildBranch, versionStamp } =
-        getVersionWithDate();
+      const extensionTelemetry = buildExtensionTelemetryProperties({
+        versionMetadata: getVersionWithDate(),
+        storage: getLocalStorage(),
+      });
       const userUid = window.roamAlphaAPI.user.uid() || "";
       const graphName = window.roamAlphaAPI.graph.name;
-      if (userUid) posthog.identify(userUid);
-      posthog.register_for_session({
-        version: version || "-",
-        buildDate: buildDate || "-",
-        buildCommit: buildCommit || "-",
-        buildBranch: buildBranch || "-",
-        versionStamp: versionStamp || "-",
+      const sessionTelemetry = {
+        ...extensionTelemetry,
         graphName,
-      });
-      posthog.capture("Extension Loaded");
+      };
+      if (userUid) posthog.identify(userUid);
+      posthog.register_for_session(sessionTelemetry);
+      posthog.capture("Extension Loaded", sessionTelemetry);
       initialized = true;
     },
   });