Use actor key for PostHog identification instead of auth state (#2044)

Co-authored-by: Claude <noreply@anthropic.com>

Author: chelojimenez

mcpjam-inspector/client/src/App.tsx

@@ -650,16 +650,19 @@ export default function App() {
 
   usePostHogIdentify();
 
+  const lastLaunchedActorRef = useRef<string | null>(null);
   useEffect(() => {
-    if (isAuthLoading) return;
+    if (!actorKey) return;
+    if (lastLaunchedActorRef.current === actorKey) return;
+    lastLaunchedActorRef.current = actorKey;
     posthog.capture("app_launched", {
       platform: detectPlatform(),
       environment: detectEnvironment(),
       user_agent: navigator.userAgent,
       version: __APP_VERSION__,
-      is_authenticated: isAuthenticated,
+      is_authenticated: Boolean(workOsUser),
     });
-  }, [isAuthLoading, isAuthenticated]);
+  }, [actorKey, workOsUser, posthog]);
 
   // Set the initial theme mode and preset on page load
   const initialThemeMode = getInitialThemeMode();

mcpjam-inspector/client/src/hooks/__tests__/usePostHogIdentify.test.ts

@@ -20,6 +20,7 @@ const mockState = vi.hoisted(() => ({
     isAuthenticated: false,
   },
   convexUser: null as { occupation?: string } | null,
+  actorKey: null as string | null,
   detectPlatform: vi.fn(() => "mac"),
 }));
 
@@ -40,13 +41,18 @@ vi.mock("@/lib/PosthogUtils", () => ({
   detectPlatform: mockState.detectPlatform,
 }));
 
+vi.mock("@/hooks/use-actor-key", () => ({
+  useActorKey: () => mockState.actorKey,
+}));
+
 describe("usePostHogIdentify", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     vi.stubGlobal("__APP_VERSION__", "2.0.13-test");
     mockState.auth.user = null;
     mockState.convexAuth.isAuthenticated = false;
     mockState.convexUser = null;
+    mockState.actorKey = null;
     mockState.detectPlatform.mockReturnValue("mac");
   });
 
@@ -58,6 +64,7 @@ describe("usePostHogIdentify", () => {
       lastName: "Smith",
     };
     mockState.convexAuth.isAuthenticated = true;
+    mockState.actorKey = "user_123";
 
     renderHook(() => usePostHogIdentify());
 
@@ -73,25 +80,57 @@ describe("usePostHogIdentify", () => {
     expect(mockState.posthog.reset).not.toHaveBeenCalled();
   });
 
-  it("re-registers static telemetry properties after logout reset", () => {
+  it("identifies guests with their guestId and does not call reset", () => {
+    mockState.auth.user = null;
+    mockState.convexAuth.isAuthenticated = false;
+    mockState.actorKey = "guest_abc";
+
     renderHook(() => usePostHogIdentify());
 
-    expect(mockState.posthog.reset).toHaveBeenCalledTimes(1);
+    expect(mockState.posthog.identify).toHaveBeenCalledWith("guest_abc", {});
     expect(mockState.posthog.register).toHaveBeenCalledWith({
-      environment: import.meta.env.MODE,
-      platform: "mac",
-      version: "2.0.13-test",
+      user_id: "guest_abc",
     });
+    expect(mockState.posthog.reset).not.toHaveBeenCalled();
   });
 
-  it("resets and re-registers static telemetry properties when auth changes from logged in to logged out", () => {
+  it("does nothing while the actor key is still resolving", () => {
+    mockState.auth.user = null;
+    mockState.actorKey = null;
+
+    renderHook(() => usePostHogIdentify());
+
+    expect(mockState.posthog.identify).not.toHaveBeenCalled();
+    expect(mockState.posthog.register).not.toHaveBeenCalled();
+    expect(mockState.posthog.reset).not.toHaveBeenCalled();
+  });
+
+  it("is idempotent across re-renders with the same guest actor key", () => {
+    mockState.auth.user = null;
+    mockState.actorKey = "guest_abc";
+
+    const { rerender } = renderHook(() => usePostHogIdentify());
+
+    expect(mockState.posthog.identify).toHaveBeenCalledTimes(1);
+    expect(mockState.posthog.register).toHaveBeenCalledTimes(1);
+
+    rerender();
+    rerender();
+
+    expect(mockState.posthog.identify).toHaveBeenCalledTimes(1);
+    expect(mockState.posthog.register).toHaveBeenCalledTimes(1);
+    expect(mockState.posthog.reset).not.toHaveBeenCalled();
+  });
+
+  it("resets and re-registers static telemetry properties when an authed user signs out into a guest session", () => {
     mockState.auth.user = {
       id: "user_123",
       email: "user@example.com",
       firstName: "Taylor",
       lastName: "Smith",
     };
     mockState.convexAuth.isAuthenticated = true;
+    mockState.actorKey = "user_123";
 
     const { rerender } = renderHook(() => usePostHogIdentify());
 
@@ -106,6 +145,7 @@ describe("usePostHogIdentify", () => {
 
     mockState.auth.user = null;
     mockState.convexAuth.isAuthenticated = false;
+    mockState.actorKey = "guest_abc";
 
     rerender();
 
@@ -115,7 +155,44 @@ describe("usePostHogIdentify", () => {
       platform: "mac",
       version: "2.0.13-test",
     });
-    expect(mockState.posthog.identify).not.toHaveBeenCalled();
+    expect(mockState.posthog.identify).toHaveBeenCalledWith("guest_abc", {});
+    expect(mockState.posthog.register).toHaveBeenCalledWith({
+      user_id: "guest_abc",
+    });
+  });
+
+  it("aliases a guest into an authed user without calling reset on guest→authed promotion", () => {
+    mockState.auth.user = null;
+    mockState.convexAuth.isAuthenticated = false;
+    mockState.actorKey = "guest_abc";
+
+    const { rerender } = renderHook(() => usePostHogIdentify());
+
+    expect(mockState.posthog.identify).toHaveBeenCalledWith("guest_abc", {});
+
+    vi.clearAllMocks();
+
+    mockState.auth.user = {
+      id: "user_123",
+      email: "user@example.com",
+      firstName: "Taylor",
+      lastName: "Smith",
+    };
+    mockState.convexAuth.isAuthenticated = true;
+    mockState.actorKey = "user_123";
+
+    rerender();
+
+    expect(mockState.posthog.reset).not.toHaveBeenCalled();
+    expect(mockState.posthog.identify).toHaveBeenCalledWith("user_123", {
+      email: "user@example.com",
+      name: "Taylor Smith",
+      first_name: "Taylor",
+      last_name: "Smith",
+    });
+    expect(mockState.posthog.register).toHaveBeenCalledWith({
+      user_id: "user_123",
+    });
   });
 
   it("adds trimmed occupation when the Convex user has one", () => {
@@ -126,6 +203,7 @@ describe("usePostHogIdentify", () => {
       lastName: "Smith",
     };
     mockState.convexAuth.isAuthenticated = true;
+    mockState.actorKey = "user_123";
     mockState.convexUser = { occupation: "  Platform Engineer  " };
 
     renderHook(() => usePostHogIdentify());
@@ -147,6 +225,7 @@ describe("usePostHogIdentify", () => {
       lastName: "Smith",
     };
     mockState.convexAuth.isAuthenticated = true;
+    mockState.actorKey = "user_123";
     mockState.convexUser = { occupation: "   " };
 
     renderHook(() => usePostHogIdentify());

mcpjam-inspector/client/src/hooks/usePostHogIdentify.ts

@@ -1,12 +1,15 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { usePostHog } from "posthog-js/react";
 import { useAuth } from "@workos-inc/authkit-react";
 import { useConvexAuth, useQuery } from "convex/react";
 import { detectPlatform } from "@/lib/PosthogUtils";
+import { useActorKey } from "@/hooks/use-actor-key";
 
 /**
- * Automatically identify users in PostHog when they log in/out
- * and set super properties that are sent with every event.
+ * Identify the active actor in PostHog using the same id the backend uses:
+ * the WorkOS user id for signed-in users, the cookie-backed guestId for
+ * guests. Reset only on a true identity switch away from an authed user, so
+ * the same browser revisiting as a guest keeps a stable distinct_id.
  */
 export function usePostHogIdentify() {
   const posthog = usePostHog();
@@ -16,13 +19,31 @@ export function usePostHogIdentify() {
     "users:getCurrentUser" as any,
     isAuthenticated ? ({} as any) : "skip"
   );
+  const actorKey = useActorKey();
+  const previousActorRef = useRef<{ key: string; wasAuthed: boolean } | null>(
+    null
+  );
 
   useEffect(() => {
     if (!posthog) return;
+    if (!actorKey) return;
+
+    const previous = previousActorRef.current;
+    const isActorChange = !previous || previous.key !== actorKey;
+    const isAuthedActor = Boolean(user) && user?.id === actorKey;
 
-    // User is authenticated - identify them
-    if (isAuthenticated && user) {
-      const personProperties: Record<string, string | null | undefined> = {
+    if (isActorChange && previous?.wasAuthed) {
+      posthog.reset();
+      posthog.register({
+        environment: import.meta.env.MODE,
+        platform: detectPlatform(),
+        version: __APP_VERSION__,
+      });
+    }
+
+    let personProperties: Record<string, string | null | undefined> = {};
+    if (isAuthedActor && user) {
+      personProperties = {
         email: user.email,
         name:
           user.firstName && user.lastName
@@ -31,30 +52,19 @@ export function usePostHogIdentify() {
         first_name: user.firstName,
         last_name: user.lastName,
       };
-
       const trimmedOccupation =
         typeof convexUser?.occupation === "string"
           ? convexUser.occupation.trim()
           : "";
       if (trimmedOccupation) {
         personProperties.occupation = trimmedOccupation;
       }
+    }
 
-      // Identify the user with their WorkOS ID
-      posthog.identify(user.id, personProperties);
-
-      posthog.register({
-        user_id: user.id,
-      });
-    } else {
-      // User logged out - reset PostHog
-      posthog.reset();
-      // Re-register static props after reset so anonymous events still have them
-      posthog.register({
-        environment: import.meta.env.MODE,
-        platform: detectPlatform(),
-        version: __APP_VERSION__,
-      });
+    posthog.identify(actorKey, personProperties);
+    if (isActorChange) {
+      posthog.register({ user_id: actorKey });
+      previousActorRef.current = { key: actorKey, wasAuthed: isAuthedActor };
     }
-  }, [posthog, isAuthenticated, user, convexUser]);
+  }, [posthog, actorKey, user, convexUser]);
 }