fix(analytics): default dev test distinct ID (#1184)

Co-authored-by: ananaBMaster <68643891+ananaBMaster@users.noreply.github.com>

src/entrypoints/background/__tests__/analytics.test.ts

@@ -1,6 +1,6 @@
 import type { FeatureUsedEventProperties } from "@/types/analytics"
 import { beforeEach, describe, expect, it, vi } from "vitest"
-import { createBackgroundAnalytics, filterAnalyticsCaptureResult } from "../analytics"
+import { createBackgroundAnalytics, filterAnalyticsCaptureResult, resolveDistinctIdOverride } from "../analytics"
 
 type RegisteredMessageHandler = (message: {
   data: FeatureUsedEventProperties
@@ -164,6 +164,20 @@ describe("background analytics", () => {
     )
   })
 
+  it("uses the dev default test UUID when no explicit override is configured", () => {
+    expect(resolveDistinctIdOverride("   ", true)).toBe("00000000-0000-0000-0000-000000000001")
+  })
+
+  it("prefers an explicit test UUID over the dev default", () => {
+    expect(resolveDistinctIdOverride("11111111-1111-1111-1111-111111111111", true)).toBe(
+      "11111111-1111-1111-1111-111111111111",
+    )
+  })
+
+  it("falls back to undefined outside dev mode when no override is configured", () => {
+    expect(resolveDistinctIdOverride("   ", false)).toBeUndefined()
+  })
+
   it("uses the test UUID override without touching install ID storage", async () => {
     storageGetItemMock.mockResolvedValueOnce(true)
 
@@ -188,6 +202,32 @@ describe("background analytics", () => {
     expect(storageSetItemMock).not.toHaveBeenCalled()
   })
 
+  it("treats blank distinct ID overrides as unset", async () => {
+    storageGetItemMock
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce("install-123")
+
+    const { captureFeatureUsedEventInBackground } = createAnalytics({
+      distinctIdOverride: "   ",
+    })
+    await captureFeatureUsedEventInBackground({
+      feature: "page_translation",
+      surface: "popup",
+      outcome: "success",
+      latency_ms: 100,
+    })
+
+    expect(posthogInitMock).toHaveBeenCalledWith(
+      "phc_test",
+      expect.objectContaining({
+        bootstrap: {
+          distinctID: "install-123",
+        },
+      }),
+    )
+    expect(storageSetItemMock).not.toHaveBeenCalled()
+  })
+
   it("warns and no-ops when PostHog env configuration is missing", async () => {
     storageGetItemMock.mockResolvedValueOnce(true)
 

src/entrypoints/background/analytics.ts

@@ -33,13 +33,39 @@ interface BackgroundAnalyticsRuntime {
   warn: typeof logger.warn
 }
 
+const DEV_POSTHOG_TEST_UUID = "00000000-0000-0000-0000-000000000001"
+
+function normalizeDistinctIdOverride(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined
+  }
+
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+export function resolveDistinctIdOverride(
+  explicitOverrideValue: string | undefined,
+  isDev: boolean,
+): string | undefined {
+  const explicitOverride = normalizeDistinctIdOverride(explicitOverrideValue)
+  if (explicitOverride) {
+    return explicitOverride
+  }
+
+  return isDev ? DEV_POSTHOG_TEST_UUID : undefined
+}
+
 function createDefaultRuntime(): BackgroundAnalyticsRuntime {
   return {
     apiHost: import.meta.env.WXT_POSTHOG_HOST,
     apiKey: import.meta.env.WXT_POSTHOG_API_KEY,
     createDistinctId: () => getRandomUUID(),
     defaultAnalyticsEnabled: DEFAULT_ANALYTICS_ENABLED,
-    distinctIdOverride: import.meta.env.WXT_POSTHOG_TEST_UUID,
+    distinctIdOverride: resolveDistinctIdOverride(
+      import.meta.env.WXT_POSTHOG_TEST_UUID,
+      import.meta.env.DEV,
+    ),
     extensionVersion: EXTENSION_VERSION,
     getStorageItem: key => storage.getItem(key as `local:${string}`),
     onMessage,
@@ -100,8 +126,9 @@ export function createBackgroundAnalytics(
   }
 
   async function getAnalyticsInstallId(): Promise<string> {
-    if (typeof runtime.distinctIdOverride === "string" && runtime.distinctIdOverride.length > 0) {
-      return runtime.distinctIdOverride
+    const distinctIdOverride = normalizeDistinctIdOverride(runtime.distinctIdOverride)
+    if (distinctIdOverride) {
+      return distinctIdOverride
     }
 
     const storageKey = `local:${ANALYTICS_INSTALL_ID_STORAGE_KEY}`