π OpenHands: AI-Driven Development
feat: add posthog events for install, conversation creation, and automations (#1036)
HeyItsChloe466164808ab0
diff --git a/.env.sample b/.env.sampleindex 88656258ff..00a1d81a5a 100644--- a/.env.sample+++ b/.env.sample@@ -16,6 +16,11 @@ VITE_FRONTEND_PORT="3001" # Port to run the frontend applicationVITE_USE_TLS="false" # Use HTTPS/WSS for proxied backend connectionsVITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification for proxied backend requests+# App-level PostHog project key β enables useTracking (identified, behaviour analytics).+# Events route to https://us.i.posthog.com under this project. Omit to disable the+# PostHogProvider entirely (useTracking calls are silently dropped).+# VITE_POSTHOG_CLIENT_KEY="phc_..."+# Deployment environment β controls which PostHog project key is compiled in.# Set to "production" or "staging" only in real deployment build pipelines.# Leave unset locally so developers never accidentally send telemetry.diff --git a/AGENTS.md b/AGENTS.mdindex 01fdcd44e5..add012e5a8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -19,6 +19,34 @@- Verification command: `npm run typecheck && npm run build`.- GitHub automation now includes `.github/workflows/ci.yml` for `npm ci`, `npm test`, and `npm run build`, plus `.github/dependabot.yml` with weekly npm/github-actions updates gated by a 7-day cooldown.+## Tracking / Analytics Architecture++Two distinct PostHog systems exist. **Never mix them at a call site.**++### System 1 β `telemetry.ts` (library-level, anonymous)+- **Purpose**: anonymous npm-consumer telemetry (`canvas_install`, `canvas_new_session`)+- **Keys**: hardcoded staging/prod keys in `telemetry.ts`; routed through `https://z.openhands.dev`+- **Consent**: `localStorage["openhands-telemetry-consent"]` via `useTelemetry` / `TelemetryConsentBanner`+- **`canvas_install`** fires once, pre-consent, per installation+- **Exports**: `trackEvent`, `useTelemetry`, `TelemetryConsentBanner`, etc. from `src/lib/index.ts` β these are the **public library API for npm consumers**+- **Rule**: Do NOT import `trackEvent` from `#/services/telemetry` in app routes or components++### System 2 β `useTracking` hook (app-level, identified)+- **Purpose**: product analytics for app behaviour events+- **Key**: `VITE_POSTHOG_CLIENT_KEY` env var β `OptionService.getConfig()` β `PostHogWrapper` β `PostHogProvider`; routed to `https://us.i.posthog.com`+- **Consent**: `user_consents_to_analytics` (backend setting) + `useSyncPostHogConsent` in `root-layout`; `AnalyticsConsentFormModal` also calls `setTelemetryConsent` to keep both systems in sync+- **All events** are typed, named functions in `src/hooks/use-tracking.ts` β add a new function there for every new event; never call `posthog.capture()` raw from a component+- **`commonProperties`** (`current_url`, `user_email`) are attached automatically by the hook+- **Rule**: Do NOT use raw `usePostHog()` + `posthog.capture()` in components β always go through `useTracking`++### Adding a new event+1. Add a typed function to `useTracking` in `src/hooks/use-tracking.ts`+2. Add the function to the hook's `return` object+3. Destructure and call it from the component: `const { trackFoo } = useTracking()`++### Env var+`VITE_POSTHOG_CLIENT_KEY` β see `.env.sample`. Without it, `PostHogProvider` never mounts and all `useTracking` calls are silently dropped (safe default for local dev).+## Runtime Services in Dev Stacks- When the agent-canvas dev launchers (`npm run dev` / `dev:minimal` / the published `agent-canvas` binary) start a stack, they set a `VITE_RUNTIME_SERVICES_INFO` env var on the frontend describing which services are running and how the agent should reach them. The frontend forwards this verbatim as `AgentContext.system_message_suffix` on every `POST /api/conversations`, so conversations land with a `<RUNTIME_SERVICES>` block appended to the system prompt.diff --git a/__tests__/api/option-service.test.ts b/__tests__/api/option-service.test.tsindex 0a9e604594..a8fe9ff317 100644--- a/__tests__/api/option-service.test.ts+++ b/__tests__/api/option-service.test.ts@@ -1,4 +1,4 @@-import { beforeEach, describe, expect, it } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { http, HttpResponse } from "msw";import {AgentServerUnavailableError,@@ -98,4 +98,27 @@ describe("OptionService", () => {expect(models.verified_providers).toEqual(["anthropic", "openhands"]);expect(models.default_model).toBeTruthy();});++ describe("posthog_client_key", () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ });++ it("returns the key from VITE_POSTHOG_CLIENT_KEY when set", async () => {+ vi.stubEnv("VITE_POSTHOG_CLIENT_KEY", "phc_test_key_123");++ const config = await OptionService.getConfig();++ expect(config.posthog_client_key).toBe("phc_test_key_123");+ });++ it("returns null when VITE_POSTHOG_CLIENT_KEY is not set", async () => {+ // No stub β env var is absent in the test environment by default,+ // so import.meta.env.VITE_POSTHOG_CLIENT_KEY is undefined,+ // and the ?? null fallback applies.+ const config = await OptionService.getConfig();++ expect(config.posthog_client_key).toBeNull();+ });+ });});diff --git a/__tests__/components/chat/chat-interface.test.tsx b/__tests__/components/chat/chat-interface.test.tsxindex 60f26228d6..b9f6d51d03 100644--- a/__tests__/components/chat/chat-interface.test.tsx+++ b/__tests__/components/chat/chat-interface.test.tsx@@ -79,6 +79,15 @@ vi.mock("#/hooks/use-agent-state", () => ({})),}));+const trackInitialQuerySubmittedMock = vi.fn();+const trackUserMessageSentMock = vi.fn();+vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => ({+ trackInitialQuerySubmitted: trackInitialQuerySubmittedMock,+ trackUserMessageSent: trackUserMessageSentMock,+ }),+}));+// Helper function to render with Router contextconst renderChatInterfaceWithRouter = () =>renderWithProviders(@@ -823,3 +832,89 @@ describe("ChatInterface - Status Indicator", () => {).not.toBeInTheDocument();});});++describe("ChatInterface - Tracking", () => {+ let queryClient: QueryClient;++ beforeEach(() => {+ vi.clearAllMocks();+ mockSend.mockResolvedValue({ queued: false });+ queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ useOptimisticUserMessageStore.setState({ pendingMessages: [] });+ useErrorMessageStore.setState({ errorMessage: null });+ (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({+ data: {},+ });+ (+ useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>+ ).mockReturnValue({+ mutateAsync: vi+ .fn()+ .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),+ isLoading: false,+ });+ useEventStore.setState({ events: [], eventIds: new Set(), uiEvents: [] });+ });++ function renderInterface() {+ render(+ <QueryClientProvider client={queryClient}>+ <MemoryRouter initialEntries={["/test-conversation-id"]}>+ <Routes>+ <Route path=":conversationId" element={<ChatInterface />} />+ </Routes>+ </MemoryRouter>+ </QueryClientProvider>,+ );+ }++ it("calls trackInitialQuerySubmitted when the first message is sent (empty conversation)", async () => {+ renderInterface();++ act(() => {+ useConversationStore.setState({ submittedMessage: "my first task" });+ });++ await waitFor(() => {+ expect(trackInitialQuerySubmittedMock).toHaveBeenCalledWith(+ expect.objectContaining({+ queryCharacterLength: "my first task".length,+ }),+ );+ });+ });++ it("calls trackUserMessageSent when a follow-up message is sent (non-empty conversation)", async () => {+ // totalEvents = uiEvents.filter(shouldRenderAgentServerEvent).length.+ // A MessageEvent (has llm_message.role + content) passes that filter,+ // so seeding uiEvents with one makes totalEvents = 1.+ useEventStore.setState({+ events: [],+ eventIds: new Set(),+ uiEvents: [+ {+ id: "e1",+ source: "user",+ llm_message: { role: "user", content: "prior message" },+ } as never,+ ],+ });++ renderInterface();++ act(() => {+ useConversationStore.setState({ submittedMessage: "follow-up" });+ });++ await waitFor(() => {+ expect(trackUserMessageSentMock).toHaveBeenCalledWith(+ expect.objectContaining({+ currentMessageLength: "follow-up".length,+ }),+ );+ });+ expect(trackInitialQuerySubmittedMock).not.toHaveBeenCalled();+ });+});diff --git a/__tests__/components/features/analytics/analytics-consent-form-modal.test.tsx b/__tests__/components/features/analytics/analytics-consent-form-modal.test.tsxnew file mode 100644index 0000000000..c42b167edb--- /dev/null+++ b/__tests__/components/features/analytics/analytics-consent-form-modal.test.tsx@@ -0,0 +1,94 @@+import { fireEvent, render, screen } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";++vi.mock("react-i18next", () => ({+ useTranslation: () => ({ t: (key: string) => key }),+}));++vi.mock("posthog-js/react", () => ({+ usePostHog: () => ({ capture: vi.fn() }),+}));++const { saveUserSettingsMock } = vi.hoisted(() => ({+ saveUserSettingsMock: vi.fn(),+}));++vi.mock("#/hooks/mutation/use-save-settings", () => ({+ useSaveSettings: () => ({ mutate: saveUserSettingsMock }),+}));++const setTelemetryConsentMock = vi.fn((_consent: string) => Promise.resolve());+vi.mock("#/services/telemetry", () => ({+ setTelemetryConsent: (consent: string) => setTelemetryConsentMock(consent),+}));++vi.mock("#/utils/handle-capture-consent", () => ({+ handleCaptureConsent: vi.fn(),+}));++// Import after mocks.+import { AnalyticsConsentFormModal } from "#/components/features/analytics/analytics-consent-form-modal";++const onCloseMock = vi.fn();++describe("AnalyticsConsentFormModal", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ // Make saveUserSettings call onSuccess immediately.+ saveUserSettingsMock.mockImplementation(+ (_data: unknown, callbacks?: { onSuccess?: () => void }) => {+ callbacks?.onSuccess?.();+ },+ );+ });++ it("calls setTelemetryConsent('granted') when user submits with analytics checked", () => {+ render(<AnalyticsConsentFormModal onClose={onCloseMock} />);++ // Checkbox is checked by default (defaultChecked).+ fireEvent.submit(screen.getByTestId("user-capture-consent-form"));++ expect(setTelemetryConsentMock).toHaveBeenCalledWith("granted");+ });++ it("calls setTelemetryConsent('denied') when user unchecks and submits", () => {+ render(<AnalyticsConsentFormModal onClose={onCloseMock} />);++ const checkbox = screen.getByRole("checkbox");+ fireEvent.click(checkbox); // uncheck+ fireEvent.submit(screen.getByTestId("user-capture-consent-form"));++ expect(setTelemetryConsentMock).toHaveBeenCalledWith("denied");+ });++ it("calls onClose after successful submission", () => {+ render(<AnalyticsConsentFormModal onClose={onCloseMock} />);++ fireEvent.submit(screen.getByTestId("user-capture-consent-form"));++ expect(onCloseMock).toHaveBeenCalled();+ });++ it("saves user_consents_to_analytics: true when checkbox is checked", () => {+ render(<AnalyticsConsentFormModal onClose={onCloseMock} />);++ fireEvent.submit(screen.getByTestId("user-capture-consent-form"));++ expect(saveUserSettingsMock).toHaveBeenCalledWith(+ { user_consents_to_analytics: true },+ expect.any(Object),+ );+ });++ it("saves user_consents_to_analytics: false when checkbox is unchecked", () => {+ render(<AnalyticsConsentFormModal onClose={onCloseMock} />);++ fireEvent.click(screen.getByRole("checkbox"));+ fireEvent.submit(screen.getByTestId("user-capture-consent-form"));++ expect(saveUserSettingsMock).toHaveBeenCalledWith(+ { user_consents_to_analytics: false },+ expect.any(Object),+ );+ });+});diff --git a/__tests__/components/features/conversation-panel/conversation-card.test.tsx b/__tests__/components/features/conversation-panel/conversation-card.test.tsxindex 2b82c901cc..31d5255f8f 100644--- a/__tests__/components/features/conversation-panel/conversation-card.test.tsx+++ b/__tests__/components/features/conversation-panel/conversation-card.test.tsx@@ -49,6 +49,12 @@ vi.mock("react-i18next", async () => {};});+vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => ({+ trackDownloadVsCodeButtonClicked: vi.fn(),+ }),+}));+describe("ConversationCard", () => {const onClick = vi.fn();const onDelete = vi.fn();diff --git a/__tests__/components/shared/modals/settings/settings-form.test.tsx b/__tests__/components/shared/modals/settings/settings-form.test.tsxindex 36febc7391..1ec0639196 100644--- a/__tests__/components/shared/modals/settings/settings-form.test.tsx+++ b/__tests__/components/shared/modals/settings/settings-form.test.tsx@@ -7,6 +7,13 @@ import { SettingsForm } from "#/components/shared/modals/settings/settings-form"import { DEFAULT_SETTINGS } from "#/services/settings";import { getAgentSettingValue } from "#/utils/sdk-settings-schema";+const trackSettingsSavedMock = vi.fn();+vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => ({+ trackSettingsSaved: trackSettingsSavedMock,+ }),+}));+describe("SettingsForm", () => {const onCloseMock = vi.fn();const saveSettingsSpy = vi.spyOn(SettingsService, "saveSettings");@@ -110,4 +117,30 @@ describe("SettingsForm", () => {expect(onCloseMock).toHaveBeenCalled();});});++ it("calls trackSettingsSaved with LLM details when form is submitted", async () => {+ renderWithProviders(+ <SettingsForm settings={DEFAULT_SETTINGS} onClose={onCloseMock} />,+ {+ navigation: { currentPath: "/settings" },+ },+ );++ await waitFor(() => {+ expect(screen.getByTestId("llm-model-input")).toHaveValue(+ expectedModelName,+ );+ });++ fireEvent.submit(screen.getByTestId("settings-form"));++ await waitFor(() => {+ expect(trackSettingsSavedMock).toHaveBeenCalledWith(+ expect.objectContaining({+ llmApiKeySet: expect.stringMatching(/^(SET|UNSET)$/),+ searchApiKeySet: expect.stringMatching(/^(SET|UNSET)$/),+ }),+ );+ });+ });});diff --git a/__tests__/hooks/mutation/use-save-settings.test.ts b/__tests__/hooks/mutation/use-save-settings.test.tsnew file mode 100644index 0000000000..988a0d2bb4--- /dev/null+++ b/__tests__/hooks/mutation/use-save-settings.test.ts@@ -0,0 +1,104 @@+import { renderHook, waitFor } from "@testing-library/react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { describe, expect, it, vi, beforeEach } from "vitest";+import React from "react";+import SettingsService from "#/api/settings-service/settings-service.api";++const trackMcpConfigUpdatedMock = vi.fn();+vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => ({+ trackMcpConfigUpdated: trackMcpConfigUpdatedMock,+ }),+}));++const useSettingsMock = vi.fn();+vi.mock("#/hooks/query/use-settings", () => ({+ useSettings: () => useSettingsMock(),+}));++import { useSaveSettings } from "#/hooks/mutation/use-save-settings";++const createWrapper = () => {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false }, mutations: { retry: false } },+ });+ return ({ children }: { children: React.ReactNode }) =>+ React.createElement(QueryClientProvider, { client: queryClient }, children);+};++describe("useSaveSettings - MCP tracking", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);+ // Default: no current mcp_config so any incoming config is treated as new.+ useSettingsMock.mockReturnValue({ data: {} });+ });++ it("calls trackMcpConfigUpdated with server counts when mcp_config changes", async () => {+ const { result } = renderHook(() => useSaveSettings(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync({+ mcp_config: {+ sse_servers: [{ url: "http://sse1" }, { url: "http://sse2" }],+ stdio_servers: [{ name: "stdio1", command: "cmd", args: [] }],+ shttp_servers: [],+ },+ });++ await waitFor(() => {+ expect(trackMcpConfigUpdatedMock).toHaveBeenCalledWith({+ sseServersCount: 2,+ stdioServersCount: 1,+ });+ });+ });++ it("does not call trackMcpConfigUpdated when mcp_config is absent in the update", async () => {+ const { result } = renderHook(() => useSaveSettings(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync({ user_consents_to_analytics: true });++ expect(trackMcpConfigUpdatedMock).not.toHaveBeenCalled();+ });++ it("does not call trackMcpConfigUpdated when mcp_config reference is unchanged", async () => {+ const sharedConfig = {+ sse_servers: [],+ stdio_servers: [],+ shttp_servers: [],+ };+ useSettingsMock.mockReturnValue({+ data: { mcp_config: sharedConfig },+ });++ const { result } = renderHook(() => useSaveSettings(), {+ wrapper: createWrapper(),+ });++ // Passing the same object reference β should not trigger tracking.+ await result.current.mutateAsync({ mcp_config: sharedConfig });++ expect(trackMcpConfigUpdatedMock).not.toHaveBeenCalled();+ });++ it("counts zero servers correctly when server arrays are empty", async () => {+ const { result } = renderHook(() => useSaveSettings(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync({+ mcp_config: { sse_servers: [], stdio_servers: [], shttp_servers: [] },+ });++ await waitFor(() => {+ expect(trackMcpConfigUpdatedMock).toHaveBeenCalledWith({+ sseServersCount: 0,+ stdioServersCount: 0,+ });+ });+ });+});diff --git a/__tests__/hooks/use-download-conversation.test.ts b/__tests__/hooks/use-download-conversation.test.tsnew file mode 100644index 0000000000..85e10d8aeb--- /dev/null+++ b/__tests__/hooks/use-download-conversation.test.ts@@ -0,0 +1,96 @@+import { renderHook, waitFor } from "@testing-library/react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { describe, expect, it, vi, beforeEach } from "vitest";+import React from "react";+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";++const trackDownloadTrajectoryButtonClickedMock = vi.fn();+vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => ({+ trackDownloadTrajectoryButtonClicked: trackDownloadTrajectoryButtonClickedMock,+ }),+}));++vi.mock("react-i18next", () => ({+ useTranslation: () => ({ t: (key: string) => key }),+}));++vi.mock("#/utils/utils", () => ({+ downloadBlob: vi.fn(),+}));++vi.mock("#/utils/custom-toast-handlers", () => ({+ displayErrorToast: vi.fn(),+}));++import { useDownloadConversation } from "#/hooks/use-download-conversation";++const createWrapper = () => {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false }, mutations: { retry: false } },+ });+ return ({ children }: { children: React.ReactNode }) =>+ React.createElement(QueryClientProvider, { client: queryClient }, children);+};++describe("useDownloadConversation - tracking", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ vi.spyOn(+ AgentServerConversationService,+ "downloadConversation",+ ).mockResolvedValue(new Blob(["data"], { type: "application/zip" }));+ });++ it("calls trackDownloadTrajectoryButtonClicked when download is triggered", async () => {+ const { result } = renderHook(() => useDownloadConversation(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync("conv-123");++ await waitFor(() => {+ expect(trackDownloadTrajectoryButtonClickedMock).toHaveBeenCalledTimes(1);+ });+ });++ it("calls trackDownloadTrajectoryButtonClicked before the API call", async () => {+ const callOrder: string[] = [];+ trackDownloadTrajectoryButtonClickedMock.mockImplementation(() => {+ callOrder.push("tracking");+ });+ vi.spyOn(+ AgentServerConversationService,+ "downloadConversation",+ ).mockImplementation(async () => {+ callOrder.push("api");+ return new Blob();+ });++ const { result } = renderHook(() => useDownloadConversation(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync("conv-123");++ expect(callOrder).toEqual(["tracking", "api"]);+ });++ it("still fires tracking even when the API subsequently rejects", async () => {+ // trackDownloadTrajectoryButtonClicked is called synchronously before+ // the await on downloadConversation, so it always fires regardless of+ // API outcome.+ vi.spyOn(+ AgentServerConversationService,+ "downloadConversation",+ ).mockRejectedValue(new Error("network error"));++ const { result } = renderHook(() => useDownloadConversation(), {+ wrapper: createWrapper(),+ });++ await result.current.mutateAsync("conv-123").catch(() => {});++ expect(trackDownloadTrajectoryButtonClickedMock).toHaveBeenCalledTimes(1);+ });+});diff --git a/__tests__/hooks/use-posthog-identify.test.ts b/__tests__/hooks/use-posthog-identify.test.tsnew file mode 100644index 0000000000..9b65db80b6--- /dev/null+++ b/__tests__/hooks/use-posthog-identify.test.ts@@ -0,0 +1,189 @@+import { renderHook } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";++const fakePosthog = {+ identify: vi.fn(),+ reset: vi.fn(),+};+let posthogInstance: typeof fakePosthog | null = fakePosthog;++vi.mock("posthog-js/react", () => ({+ usePostHog: () => posthogInstance,+}));++const useSettingsMock = vi.fn();+vi.mock("#/hooks/query/use-settings", () => ({+ useSettings: () => useSettingsMock(),+}));++const useActiveBackendMock = vi.fn();+vi.mock("#/contexts/active-backend-context", () => ({+ useActiveBackend: () => useActiveBackendMock(),+}));++const useCloudCurrentUserIdMock = vi.fn();+vi.mock("#/hooks/query/use-cloud-current-user-id", () => ({+ useCloudCurrentUserId: () => useCloudCurrentUserIdMock(),+}));++import { usePostHogIdentify } from "#/hooks/use-posthog-identify";++const BACKEND_ID = "cloud-1";+const cloudBackend = { kind: "cloud" as const, id: BACKEND_ID };+const localBackend = { kind: "local" as const, id: "local-1" };++describe("usePostHogIdentify", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ posthogInstance = fakePosthog;+ useActiveBackendMock.mockReturnValue({ backend: cloudBackend });+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true, email: "[email protected]" },+ });+ useCloudCurrentUserIdMock.mockReturnValue({+ [BACKEND_ID]: { userId: "user-123", isLoading: false },+ });+ });++ describe("no-op guards", () => {+ it("does nothing when backend is local mode", () => {+ useActiveBackendMock.mockReturnValue({ backend: localBackend });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).not.toHaveBeenCalled();+ expect(fakePosthog.reset).not.toHaveBeenCalled();+ });++ it("does nothing when posthog is not available", () => {+ posthogInstance = null;++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).not.toHaveBeenCalled();+ expect(fakePosthog.reset).not.toHaveBeenCalled();+ });++ it("does nothing while settings are still loading (data === undefined)", () => {+ useSettingsMock.mockReturnValue({ data: undefined });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).not.toHaveBeenCalled();+ expect(fakePosthog.reset).not.toHaveBeenCalled();+ });++ it("does nothing when consent is null (decision not yet made)", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: null, email: "[email protected]" },+ });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).not.toHaveBeenCalled();+ expect(fakePosthog.reset).not.toHaveBeenCalled();+ });++ it("does nothing when consent is true but userId has not loaded yet", () => {+ useCloudCurrentUserIdMock.mockReturnValue({+ [BACKEND_ID]: { userId: null, isLoading: true },+ });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).not.toHaveBeenCalled();+ expect(fakePosthog.reset).not.toHaveBeenCalled();+ });+ });++ describe("identify", () => {+ it("calls posthog.identify with userId and email when consent is true", () => {+ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).toHaveBeenCalledOnce();+ expect(fakePosthog.identify).toHaveBeenCalledWith("user-123", {+ email: "[email protected]",+ });+ });++ it("omits email from traits when settings.email is not set", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true, email: undefined },+ });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).toHaveBeenCalledWith("user-123", {+ email: undefined,+ });+ });++ it("re-identifies with updated traits when email changes", () => {+ const { rerender } = renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).toHaveBeenCalledOnce();++ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true, email: "[email protected]" },+ });+ rerender();++ expect(fakePosthog.identify).toHaveBeenCalledTimes(2);+ expect(fakePosthog.identify).toHaveBeenLastCalledWith("user-123", {+ email: "[email protected]",+ });+ });+ });++ describe("reset", () => {+ it("calls posthog.reset when consent is explicitly false", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: false, email: "[email protected]" },+ });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.reset).toHaveBeenCalledOnce();+ expect(fakePosthog.identify).not.toHaveBeenCalled();+ });++ it("calls posthog.reset when userId becomes null after a prior identify (logout)", () => {+ const { rerender } = renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).toHaveBeenCalledOnce();++ useCloudCurrentUserIdMock.mockReturnValue({+ [BACKEND_ID]: { userId: null, isLoading: false },+ });+ rerender();++ expect(fakePosthog.reset).toHaveBeenCalledOnce();+ });++ it("does not call posthog.reset on initial render when userId is null with no prior identify", () => {+ useCloudCurrentUserIdMock.mockReturnValue({+ [BACKEND_ID]: { userId: null, isLoading: false },+ });++ renderHook(() => usePostHogIdentify());++ expect(fakePosthog.reset).not.toHaveBeenCalled();+ expect(fakePosthog.identify).not.toHaveBeenCalled();+ });++ it("calls posthog.reset when consent changes from true to false after identify", () => {+ const { rerender } = renderHook(() => usePostHogIdentify());++ expect(fakePosthog.identify).toHaveBeenCalledOnce();+ fakePosthog.identify.mockClear();++ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: false, email: "[email protected]" },+ });+ rerender();++ expect(fakePosthog.reset).toHaveBeenCalledOnce();+ expect(fakePosthog.identify).not.toHaveBeenCalled();+ });+ });+});diff --git a/__tests__/hooks/use-sync-posthog-consent.test.ts b/__tests__/hooks/use-sync-posthog-consent.test.tsnew file mode 100644index 0000000000..1343d4cbe2--- /dev/null+++ b/__tests__/hooks/use-sync-posthog-consent.test.ts@@ -0,0 +1,118 @@+import { renderHook } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";++// usePostHog must be controllable per-test so use vi.hoisted.+const { usePostHogMock } = vi.hoisted(() => ({+ usePostHogMock: vi.fn(),+}));++vi.mock("posthog-js/react", () => ({+ usePostHog: usePostHogMock,+}));++const useSettingsMock = vi.fn();+vi.mock("#/hooks/query/use-settings", () => ({+ useSettings: () => useSettingsMock(),+}));++const handleCaptureConsentMock = vi.fn();+vi.mock("#/utils/handle-capture-consent", () => ({+ handleCaptureConsent: (...args: unknown[]) =>+ handleCaptureConsentMock(...args),+}));++// Import after mocks so the module sees the stubbed dependencies.+import { useSyncPostHogConsent } from "#/hooks/use-sync-posthog-consent";++const fakePosthog = { capture: vi.fn() };++describe("useSyncPostHogConsent", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ usePostHogMock.mockReturnValue(fakePosthog);+ });++ it("calls opt-out when user_consents_to_analytics is null", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: null },+ });++ renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, false);+ });++ it("calls opt-out when user_consents_to_analytics is false", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: false },+ });++ renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, false);+ });++ it("calls opt-in when user_consents_to_analytics is true", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true },+ });++ renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, true);+ });++ it("does nothing while settings are still loading (data === undefined)", () => {+ useSettingsMock.mockReturnValue({ data: undefined });++ renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).not.toHaveBeenCalled();+ });++ it("does nothing when posthog is not yet available", () => {+ usePostHogMock.mockReturnValue(null);+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true },+ });++ renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).not.toHaveBeenCalled();+ });++ it("re-syncs when settings update from null to true (consent granted after load)", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: null },+ });++ const { rerender } = renderHook(() => useSyncPostHogConsent());++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, false);+ handleCaptureConsentMock.mockClear();++ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true },+ });+ rerender();++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, true);+ });++ it("re-syncs when settings update from true to false (consent revoked)", () => {+ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: true },+ });++ const { rerender } = renderHook(() => useSyncPostHogConsent());++ handleCaptureConsentMock.mockClear();++ useSettingsMock.mockReturnValue({+ data: { user_consents_to_analytics: false },+ });+ rerender();++ expect(handleCaptureConsentMock).toHaveBeenCalledWith(fakePosthog, false);+ });+});diff --git a/__tests__/hooks/use-tracking.test.ts b/__tests__/hooks/use-tracking.test.tsnew file mode 100644index 0000000000..118d84eb5b--- /dev/null+++ b/__tests__/hooks/use-tracking.test.ts@@ -0,0 +1,315 @@+import { renderHook } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";++const captureMock = vi.fn();+let posthogMock: { capture: typeof captureMock } | undefined = {+ capture: captureMock,+};++vi.mock("posthog-js/react", () => ({+ usePostHog: () => posthogMock,+}));++const useSettingsMock = vi.fn();+vi.mock("#/hooks/query/use-settings", () => ({+ useSettings: () => useSettingsMock(),+}));++import { useTracking } from "#/hooks/use-tracking";++const TEST_EMAIL = "[email protected]";+// Resolved at test-run time so it matches whatever URL jsdom is configured+// with in the current environment (varies between local and CI).+let COMMON: { current_url: string; user_email: string };++describe("useTracking", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ posthogMock = { capture: captureMock };+ useSettingsMock.mockReturnValue({+ data: { email: TEST_EMAIL, user_consents_to_analytics: true },+ });+ COMMON = {+ current_url: window.location.href,+ user_email: TEST_EMAIL,+ };+ });++ const getTracking = () => renderHook(() => useTracking()).result.current;++ describe("trackLoginButtonClick", () => {+ it("captures login_button_clicked with provider and commonProperties", () => {+ getTracking().trackLoginButtonClick({ provider: "github" });++ expect(captureMock).toHaveBeenCalledWith("login_button_clicked", {+ provider: "github",+ ...COMMON,+ });+ });+ });++ describe("trackConversationCreated", () => {+ it("captures conversation_created with has_repository flag", () => {+ getTracking().trackConversationCreated({ hasRepository: true });++ expect(captureMock).toHaveBeenCalledWith("conversation_created", {+ has_repository: true,+ ...COMMON,+ });+ });+ });++ describe("trackPushButtonClick", () => {+ it("captures push_button_clicked with commonProperties", () => {+ getTracking().trackPushButtonClick();++ expect(captureMock).toHaveBeenCalledWith(+ "push_button_clicked",+ expect.objectContaining(COMMON),+ );+ });+ });++ describe("trackPullButtonClick", () => {+ it("captures pull_button_clicked with commonProperties", () => {+ getTracking().trackPullButtonClick();++ expect(captureMock).toHaveBeenCalledWith(+ "pull_button_clicked",+ expect.objectContaining(COMMON),+ );+ });+ });++ describe("trackCreatePrButtonClick", () => {+ it("captures create_pr_button_clicked with commonProperties", () => {+ getTracking().trackCreatePrButtonClick();++ expect(captureMock).toHaveBeenCalledWith(+ "create_pr_button_clicked",+ expect.objectContaining(COMMON),+ );+ });+ });++ describe("trackUserSignupCompleted", () => {+ it("captures user_signup_completed with signup_timestamp and commonProperties", () => {+ getTracking().trackUserSignupCompleted();++ expect(captureMock).toHaveBeenCalledWith(+ "user_signup_completed",+ expect.objectContaining({+ signup_timestamp: expect.any(String),+ ...COMMON,+ }),+ );+ });+ });++ describe("trackPrebuiltAutomationEnabled", () => {+ it("captures prebuilt_automation_enabled with all fields", () => {+ getTracking().trackPrebuiltAutomationEnabled({+ automationId: "auto-1",+ automationName: "My Automation",+ automationCategory: "CI",+ });++ expect(captureMock).toHaveBeenCalledWith("prebuilt_automation_enabled", {+ automation_id: "auto-1",+ automation_name: "My Automation",+ automation_category: "CI",+ ...COMMON,+ });+ });++ it("sends undefined fields when optional args are omitted", () => {+ getTracking().trackPrebuiltAutomationEnabled({+ automationName: "Minimal",+ });++ expect(captureMock).toHaveBeenCalledWith(+ "prebuilt_automation_enabled",+ expect.objectContaining({+ automation_name: "Minimal",+ automation_id: undefined,+ automation_category: undefined,+ }),+ );+ });+ });++ describe("trackInitialQuerySubmitted", () => {+ it("captures initial_query_submitted with all properties", () => {+ getTracking().trackInitialQuerySubmitted({+ entryPoint: "github",+ queryCharacterLength: 42,+ replayJsonSize: 100,+ });++ expect(captureMock).toHaveBeenCalledWith("initial_query_submitted", {+ entry_point: "github",+ query_character_length: 42,+ replay_json_size: 100,+ ...COMMON,+ });+ });++ it("sends undefined replayJsonSize when omitted", () => {+ getTracking().trackInitialQuerySubmitted({+ entryPoint: "direct",+ queryCharacterLength: 10,+ });++ expect(captureMock).toHaveBeenCalledWith(+ "initial_query_submitted",+ expect.objectContaining({ replay_json_size: undefined }),+ );+ });+ });++ describe("trackUserMessageSent", () => {+ it("captures user_message_sent with message counts", () => {+ getTracking().trackUserMessageSent({+ sessionMessageCount: 5,+ currentMessageLength: 120,+ });++ expect(captureMock).toHaveBeenCalledWith("user_message_sent", {+ session_message_count: 5,+ current_message_length: 120,+ ...COMMON,+ });+ });+ });++ describe("trackDownloadVsCodeButtonClicked", () => {+ it("captures download_via_vscode_button_clicked with commonProperties", () => {+ getTracking().trackDownloadVsCodeButtonClicked();++ expect(captureMock).toHaveBeenCalledWith(+ "download_via_vscode_button_clicked",+ expect.objectContaining(COMMON),+ );+ });+ });++ describe("trackSettingsSaved", () => {+ it("captures settings_saved with all properties using SCREAMING_SNAKE_CASE keys", () => {+ getTracking().trackSettingsSaved({+ llmModel: "gpt-4",+ llmApiKeySet: "SET",+ searchApiKeySet: "UNSET",+ remoteRuntimeResourceFactor: 2,+ });++ expect(captureMock).toHaveBeenCalledWith("settings_saved", {+ LLM_MODEL: "gpt-4",+ LLM_API_KEY_SET: "SET",+ SEARCH_API_KEY_SET: "UNSET",+ REMOTE_RUNTIME_RESOURCE_FACTOR: 2,+ ...COMMON,+ });+ });+ });++ describe("trackMcpConfigUpdated", () => {+ it("captures mcp_config_updated with server counts and has_mcp_config: true", () => {+ getTracking().trackMcpConfigUpdated({+ sseServersCount: 2,+ stdioServersCount: 1,+ });++ expect(captureMock).toHaveBeenCalledWith("mcp_config_updated", {+ has_mcp_config: true,+ sse_servers_count: 2,+ stdio_servers_count: 1,+ ...COMMON,+ });+ });+ });++ describe("trackDownloadTrajectoryButtonClicked", () => {+ it("captures download_trajectory_button_clicked with commonProperties", () => {+ getTracking().trackDownloadTrajectoryButtonClicked();++ expect(captureMock).toHaveBeenCalledWith(+ "download_trajectory_button_clicked",+ expect.objectContaining(COMMON),+ );+ });+ });++ describe("consent gate", () => {+ it("does not capture when posthog is not initialized", () => {+ posthogMock = undefined;++ getTracking().trackPushButtonClick();++ expect(captureMock).not.toHaveBeenCalled();+ });++ it("does not capture when user_consents_to_analytics is false", () => {+ useSettingsMock.mockReturnValue({+ data: { email: TEST_EMAIL, user_consents_to_analytics: false },+ });++ getTracking().trackPushButtonClick();++ expect(captureMock).not.toHaveBeenCalled();+ });++ it("does not capture when user_consents_to_analytics is null", () => {+ useSettingsMock.mockReturnValue({+ data: { email: TEST_EMAIL, user_consents_to_analytics: null },+ });++ getTracking().trackPushButtonClick();++ expect(captureMock).not.toHaveBeenCalled();+ });++ it("does not capture when settings are still loading", () => {+ useSettingsMock.mockReturnValue({ data: undefined });++ getTracking().trackPushButtonClick();++ expect(captureMock).not.toHaveBeenCalled();+ });+ });++ describe("commonProperties", () => {+ it("uses git_user_email as fallback when email is absent", () => {+ useSettingsMock.mockReturnValue({+ data: {+ email: null,+ git_user_email: "[email protected]",+ user_consents_to_analytics: true,+ },+ });++ getTracking().trackPushButtonClick();++ expect(captureMock).toHaveBeenCalledWith(+ "push_button_clicked",+ expect.objectContaining({ user_email: "[email protected]" }),+ );+ });++ it("sends null user_email when no email fields are present", () => {+ useSettingsMock.mockReturnValue({+ data: {+ email: null,+ git_user_email: null,+ user_consents_to_analytics: true,+ },+ });++ getTracking().trackPushButtonClick();++ expect(captureMock).toHaveBeenCalledWith(+ "push_button_clicked",+ expect.objectContaining({ user_email: null }),+ );+ });+ });+});diff --git a/__tests__/routes/root-layout.test.tsx b/__tests__/routes/root-layout.test.tsxindex 0d607ed974..1602405aa8 100644--- a/__tests__/routes/root-layout.test.tsx+++ b/__tests__/routes/root-layout.test.tsx@@ -26,6 +26,10 @@ vi.mock("#/hooks/use-sync-posthog-consent", () => ({useSyncPostHogConsent: () => {},}));+vi.mock("#/hooks/use-posthog-identify", () => ({+ usePostHogIdentify: () => {},+}));+vi.mock("#/hooks/use-app-title", () => ({useAppTitle: () => "OpenHands",}));diff --git a/src/api/option-service/option-service.api.ts b/src/api/option-service/option-service.api.tsindex 80ee208a63..a062faa548 100644--- a/src/api/option-service/option-service.api.ts+++ b/src/api/option-service/option-service.api.ts@@ -31,7 +31,8 @@ class OptionService {await loadAgentServerInfo();return {- posthog_client_key: null,+ posthog_client_key:+ (import.meta.env.VITE_POSTHOG_CLIENT_KEY as string | undefined) ?? null,feature_flags: {hide_llm_settings: false,hide_users_page: true,diff --git a/src/components/features/analytics/analytics-consent-form-modal.tsx b/src/components/features/analytics/analytics-consent-form-modal.tsxindex 32bce9d375..1384658abc 100644--- a/src/components/features/analytics/analytics-consent-form-modal.tsx+++ b/src/components/features/analytics/analytics-consent-form-modal.tsx@@ -8,6 +8,7 @@ import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";import { ModalBody } from "#/components/shared/modals/modal-body";import { useSaveSettings } from "#/hooks/mutation/use-save-settings";import { handleCaptureConsent } from "#/utils/handle-capture-consent";+import { setTelemetryConsent } from "#/services/telemetry";import { BrandButton } from "../settings/brand-button";import { I18nKey } from "#/i18n/declaration";@@ -32,6 +33,9 @@ export function AnalyticsConsentFormModal({{onSuccess: () => {handleCaptureConsent(posthog, analytics);+ // Sync telemetry.ts consent so canvas_new_session and any+ // trackEvent() calls respect the same user decision.+ void setTelemetryConsent(analytics ? "granted" : "denied");onClose();},},diff --git a/src/components/features/automations/recommended-automations-launcher.tsx b/src/components/features/automations/recommended-automations-launcher.tsxindex ed2841aa3c..e5b333454f 100644--- a/src/components/features/automations/recommended-automations-launcher.tsx+++ b/src/components/features/automations/recommended-automations-launcher.tsx@@ -22,6 +22,7 @@ import {getMcpMarketplaceCatalog,} from "#/utils/mcp-marketplace-utils";import { InstallServerModal } from "#/components/features/mcp-page/install-server-modal";+import { useTracking } from "#/hooks/use-tracking";import { RecommendedAutomationsSection } from "./recommended-automations-section";interface RecommendedAutomationsLauncherProps {@@ -88,6 +89,7 @@ export function RecommendedAutomationsLauncher({const activeBackend = useActiveBackend();const { navigate } = useNavigation();const { data: settings } = useSettings();+ const { trackPrebuiltAutomationEnabled } = useTracking();const createConversation = useCreateConversation();const isCreatingConversation = useIsCreatingConversation();const setMessageToSend = useConversationStore(@@ -126,6 +128,10 @@ export function RecommendedAutomationsLauncher({{},{onSuccess: (conversation) => {+ trackPrebuiltAutomationEnabled({+ automationName: automation.name,+ automationCategory: automation.category,+ });if (conversation.conversation_id.startsWith("task-") &&conversation.task_id@@ -153,6 +159,7 @@ export function RecommendedAutomationsLauncher({navigate,onLaunched,setMessageToSend,+ trackPrebuiltAutomationEnabled,],);diff --git a/src/components/features/chat/chat-interface.tsx b/src/components/features/chat/chat-interface.tsxindex e16a0cc4d6..1e4b28e945 100644--- a/src/components/features/chat/chat-interface.tsx+++ b/src/components/features/chat/chat-interface.tsx@@ -1,5 +1,5 @@import React from "react";-import { usePostHog } from "posthog-js/react";+import { useTracking } from "#/hooks/use-tracking";import { useTranslation } from "react-i18next";import { convertImageToBase64 } from "#/utils/convert-image-to-base-64";import { createChatMessage } from "#/services/chat-service";@@ -53,7 +53,7 @@ function getEntryPoint(}export function ChatInterface() {- const posthog = usePostHog();+ const { trackInitialQuerySubmitted, trackUserMessageSent } = useTracking();const { setMessageToSend } = useConversationStore();const { errorMessage, removeErrorMessage, setErrorMessage } =useErrorMessageStore();@@ -279,18 +279,18 @@ export function ChatInterface() {const images = [...originalImages];const files = [...originalFiles];if (totalEvents === 0) {- posthog.capture("initial_query_submitted", {- entry_point: getEntryPoint(+ trackInitialQuerySubmitted({+ entryPoint: getEntryPoint(selectedRepository !== null,replayJson !== null,),- query_character_length: content.length,- replay_json_size: replayJson?.length,+ queryCharacterLength: content.length,+ replayJsonSize: replayJson?.length,});} else {- posthog.capture("user_message_sent", {- session_message_count: totalEvents,- current_message_length: content.length,+ trackUserMessageSent({+ sessionMessageCount: totalEvents,+ currentMessageLength: content.length,});}diff --git a/src/components/features/conversation-panel/conversation-card/conversation-card.tsx b/src/components/features/conversation-panel/conversation-card/conversation-card.tsxindex c4006977c0..3dc84d874a 100644--- a/src/components/features/conversation-panel/conversation-card/conversation-card.tsx+++ b/src/components/features/conversation-panel/conversation-card/conversation-card.tsx@@ -1,5 +1,5 @@import React from "react";-import { usePostHog } from "posthog-js/react";+import { useTracking } from "#/hooks/use-tracking";import { cn } from "#/utils/utils";import { transformVSCodeUrl } from "#/utils/vscode-url-helper";import ConversationService from "#/api/conversation-service/conversation-service.api";@@ -60,7 +60,7 @@ export function ConversationCard({agentKind = null,acpServer = null,}: ConversationCardProps) {- const posthog = usePostHog();+ const { trackDownloadVsCodeButtonClicked } = useTracking();const [titleMode, setTitleMode] = React.useState<"view" | "edit">("view");const { mutateAsync: downloadConversation } = useDownloadConversation();@@ -97,7 +97,7 @@ export function ConversationCard({) => {event.preventDefault();event.stopPropagation();- posthog.capture("download_via_vscode_button_clicked");+ trackDownloadVsCodeButtonClicked();// Fetch the VS Code URL from the APIif (conversationId) {diff --git a/src/components/shared/modals/settings/settings-form.tsx b/src/components/shared/modals/settings/settings-form.tsxindex e4981b3c8d..3445e03c2a 100644--- a/src/components/shared/modals/settings/settings-form.tsx+++ b/src/components/shared/modals/settings/settings-form.tsx@@ -1,6 +1,6 @@import { useTranslation } from "react-i18next";import React from "react";-import { usePostHog } from "posthog-js/react";+import { useTracking } from "#/hooks/use-tracking";import { useNavigation } from "#/context/navigation-context";import { I18nKey } from "#/i18n/declaration";import { DangerModal } from "../confirmation-modals/danger-modal";@@ -21,7 +21,7 @@ interface SettingsFormProps {}export function SettingsForm({ settings, onClose }: SettingsFormProps) {- const posthog = usePostHog();+ const { trackSettingsSaved } = useTracking();const { mutate: saveUserSettings } = useSaveSettings();const { currentPath } = useNavigation();const { t } = useTranslation("openhands");@@ -41,11 +41,11 @@ export function SettingsForm({ settings, onClose }: SettingsFormProps) {const agentLlm =((newSettings.agent_settings_diff as Record<string, unknown>)?.llm as Record<string, unknown>) ?? {};- posthog.capture("settings_saved", {- LLM_MODEL: agentLlm.model,- LLM_API_KEY_SET: agentLlm.api_key ? "SET" : "UNSET",- SEARCH_API_KEY_SET: newSettings.search_api_key ? "SET" : "UNSET",- REMOTE_RUNTIME_RESOURCE_FACTOR:+ trackSettingsSaved({+ llmModel: agentLlm.model,+ llmApiKeySet: agentLlm.api_key ? "SET" : "UNSET",+ searchApiKeySet: newSettings.search_api_key ? "SET" : "UNSET",+ remoteRuntimeResourceFactor:newSettings.remote_runtime_resource_factor,});},diff --git a/src/hooks/mutation/use-save-settings.ts b/src/hooks/mutation/use-save-settings.tsindex 6ef1ca92ad..a52f481523 100644--- a/src/hooks/mutation/use-save-settings.ts+++ b/src/hooks/mutation/use-save-settings.ts@@ -1,5 +1,5 @@import { useMutation, useQueryClient } from "@tanstack/react-query";-import { usePostHog } from "posthog-js/react";+import { useTracking } from "#/hooks/use-tracking";import SettingsService from "#/api/settings-service/settings-service.api";import {MCPConfig,@@ -60,7 +60,7 @@ const saveSettingsMutationFn = async (settings: SettingsUpdate) => {};export const useSaveSettings = (scope: SettingsScope = "personal") => {- const posthog = usePostHog();+ const { trackMcpConfigUpdated } = useTracking();const queryClient = useQueryClient();const { data: currentSettings } = useSettings(scope);@@ -72,10 +72,9 @@ export const useSaveSettings = (scope: SettingsScope = "personal") => {| undefined;if (nextMcpConfig && currentMcpConfig !== nextMcpConfig) {- posthog.capture("mcp_config_updated", {- has_mcp_config: true,- sse_servers_count: nextMcpConfig.sse_servers?.length || 0,- stdio_servers_count: nextMcpConfig.stdio_servers?.length || 0,+ trackMcpConfigUpdated({+ sseServersCount: nextMcpConfig.sse_servers?.length ?? 0,+ stdioServersCount: nextMcpConfig.stdio_servers?.length ?? 0,});}diff --git a/src/hooks/use-download-conversation.ts b/src/hooks/use-download-conversation.tsindex 25b91f54e4..bb4a2d1fbb 100644--- a/src/hooks/use-download-conversation.ts+++ b/src/hooks/use-download-conversation.ts@@ -1,5 +1,5 @@import { useMutation } from "@tanstack/react-query";-import { usePostHog } from "posthog-js/react";+import { useTracking } from "#/hooks/use-tracking";import { useTranslation } from "react-i18next";import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";import { downloadBlob } from "#/utils/utils";@@ -7,13 +7,13 @@ import { displayErrorToast } from "#/utils/custom-toast-handlers";import { I18nKey } from "#/i18n/declaration";export const useDownloadConversation = () => {- const posthog = usePostHog();+ const { trackDownloadTrajectoryButtonClicked } = useTracking();const { t } = useTranslation("openhands");return useMutation({mutationKey: ["conversations", "download"],mutationFn: async (conversationId: string) => {- posthog.capture("download_trajectory_button_clicked");+ trackDownloadTrajectoryButtonClicked();const blob =await AgentServerConversationService.downloadConversation(conversationId,diff --git a/src/hooks/use-posthog-identify.ts b/src/hooks/use-posthog-identify.tsnew file mode 100644index 0000000000..cadf970d07--- /dev/null+++ b/src/hooks/use-posthog-identify.ts@@ -0,0 +1,45 @@+import React from "react";+import { usePostHog } from "posthog-js/react";+import { useActiveBackend } from "#/contexts/active-backend-context";+import { useCloudCurrentUserId } from "#/hooks/query/use-cloud-current-user-id";+import { useSettings } from "#/hooks/query/use-settings";++/**+ * Calls posthog.identify() for cloud users who have granted analytics consent.+ *+ * Cloud mode only β local mode has no stable server-issued user ID and+ * person_profiles="identified_only" would silently drop all events anyway.+ *+ * Identity lifecycle:+ * - consent === true + userId present β posthog.identify(userId, { email })+ * - consent === false (explicit denial) β posthog.reset()+ * - userId becomes null after identify β posthog.reset() (logout)+ * - consent === null / settings loading β no-op (wait for decision)+ */+export const usePostHogIdentify = () => {+ const posthog = usePostHog();+ const { backend } = useActiveBackend();+ const { data: settings } = useSettings();+ const userIds = useCloudCurrentUserId();+ const hasIdentifiedRef = React.useRef(false);++ const isCloud = backend.kind === "cloud";+ const userId = isCloud ? (userIds[backend.id]?.userId ?? null) : null;+ const consent = settings?.user_consents_to_analytics;++ React.useEffect(() => {+ if (!posthog || !isCloud || settings === undefined) return;++ if (consent === true && userId) {+ posthog.identify(userId, { email: settings.email ?? undefined });+ hasIdentifiedRef.current = true;+ return;+ }++ // Reset on explicit denial or on logout (userId gone after a prior identify)+ if (consent === false || (hasIdentifiedRef.current && !userId)) {+ posthog.reset();+ hasIdentifiedRef.current = false;+ }+ }, [posthog, isCloud, consent, userId, settings?.email, settings]);+};diff --git a/src/hooks/use-sync-posthog-consent.ts b/src/hooks/use-sync-posthog-consent.tsindex 5032122794..f9a27ac09d 100644--- a/src/hooks/use-sync-posthog-consent.ts+++ b/src/hooks/use-sync-posthog-consent.ts@@ -4,38 +4,26 @@ import { handleCaptureConsent } from "#/utils/handle-capture-consent";import { useSettings } from "./query/use-settings";/**- * Hook to sync PostHog opt-in/out state with backend setting on mount.- * This ensures that if the backend setting changes (e.g., via API or different client),- * the PostHog instance reflects the current user preference.+ * Hook to sync PostHog opt-in/out state with the backend setting.+ *+ * Runs whenever settings change so that a consent decision made in one tab+ * or via the API is picked up without a page reload.+ *+ * Consent model:+ * true β opt in (user explicitly accepted)+ * false β opt out (user explicitly denied)+ * null β opt out (consent not yet collected β safe default while loading+ * or on first visit, prevents capturing before the user has decided)*/export const useSyncPostHogConsent = () => {const posthog = usePostHog();const { data: settings } = useSettings();- const hasSyncedRef = React.useRef(false);React.useEffect(() => {- // Only run once when both PostHog and settings are available- if (!posthog || settings === undefined || hasSyncedRef.current) {- return;- }+ if (!posthog || settings === undefined) return;- const backendConsent = settings.user_consents_to_analytics;-- // Only sync if there's a backend preference set- if (backendConsent !== null) {- const posthogHasOptedIn = posthog.has_opted_in_capturing();- const posthogHasOptedOut = posthog.has_opted_out_capturing();-- // Check if PostHog state is out of sync with backend- const needsSync =- (backendConsent === true && !posthogHasOptedIn) ||- (backendConsent === false && !posthogHasOptedOut);-- if (needsSync) {- handleCaptureConsent(posthog, backendConsent);- }-- hasSyncedRef.current = true;- }+ // null and false are both treated as "not consented".+ // Only an explicit true opts PostHog in.+ handleCaptureConsent(posthog, settings.user_consents_to_analytics === true);}, [posthog, settings]);};diff --git a/src/hooks/use-tracking.ts b/src/hooks/use-tracking.tsindex 9c2e333e00..6e3f1de57e 100644--- a/src/hooks/use-tracking.ts+++ b/src/hooks/use-tracking.ts@@ -5,6 +5,11 @@ import { Provider } from "#/types/settings";/*** Hook that provides tracking functions with automatic data collection* from available hooks (settings, etc.)+ *+ * All events require explicit user consent (user_consents_to_analytics === true).+ * Events are silently dropped when:+ * - posthog is not initialized (VITE_POSTHOG_CLIENT_KEY not set)+ * - user_consents_to_analytics is false or null (consent not yet collected)*/export const useTracking = () => {const posthog = usePostHog();@@ -16,11 +21,17 @@ export const useTracking = () => {user_email: settings?.email || settings?.git_user_email || null,};+ /**+ * Capture an event only when PostHog is available and the user has+ * explicitly consented. null and false are both treated as "not consented".+ */+ const track = (event: string, properties: Record<string, unknown> = {}) => {+ if (!posthog || settings?.user_consents_to_analytics !== true) return;+ posthog.capture(event, { ...properties, ...commonProperties });+ };+const trackLoginButtonClick = ({ provider }: { provider: Provider }) => {- posthog.capture("login_button_clicked", {- provider,- ...commonProperties,- });+ track("login_button_clicked", { provider });};const trackConversationCreated = ({@@ -28,37 +39,113 @@ export const useTracking = () => {}: {hasRepository: boolean;}) => {- posthog.capture("conversation_created", {- has_repository: hasRepository,- ...commonProperties,- });+ track("conversation_created", { has_repository: hasRepository });};const trackPushButtonClick = () => {- posthog.capture("push_button_clicked", {- ...commonProperties,- });+ track("push_button_clicked");};const trackPullButtonClick = () => {- posthog.capture("pull_button_clicked", {- ...commonProperties,- });+ track("pull_button_clicked");};const trackCreatePrButtonClick = () => {- posthog.capture("create_pr_button_clicked", {- ...commonProperties,- });+ track("create_pr_button_clicked");};const trackUserSignupCompleted = () => {- posthog.capture("user_signup_completed", {+ track("user_signup_completed", {signup_timestamp: new Date().toISOString(),- ...commonProperties,});};+ const trackPrebuiltAutomationEnabled = ({+ automationId,+ automationName,+ automationCategory,+ }: {+ automationId?: string;+ automationName: string;+ automationCategory?: string;+ }) => {+ track("prebuilt_automation_enabled", {+ automation_id: automationId,+ automation_name: automationName,+ automation_category: automationCategory,+ });+ };++ const trackInitialQuerySubmitted = ({+ entryPoint,+ queryCharacterLength,+ replayJsonSize,+ }: {+ entryPoint: string;+ queryCharacterLength: number;+ replayJsonSize?: number;+ }) => {+ track("initial_query_submitted", {+ entry_point: entryPoint,+ query_character_length: queryCharacterLength,+ replay_json_size: replayJsonSize,+ });+ };++ const trackUserMessageSent = ({+ sessionMessageCount,+ currentMessageLength,+ }: {+ sessionMessageCount: number;+ currentMessageLength: number;+ }) => {+ track("user_message_sent", {+ session_message_count: sessionMessageCount,+ current_message_length: currentMessageLength,+ });+ };++ const trackDownloadVsCodeButtonClicked = () => {+ track("download_via_vscode_button_clicked");+ };++ const trackSettingsSaved = ({+ llmModel,+ llmApiKeySet,+ searchApiKeySet,+ remoteRuntimeResourceFactor,+ }: {+ llmModel: unknown;+ llmApiKeySet: "SET" | "UNSET";+ searchApiKeySet: "SET" | "UNSET";+ remoteRuntimeResourceFactor?: unknown;+ }) => {+ track("settings_saved", {+ LLM_MODEL: llmModel,+ LLM_API_KEY_SET: llmApiKeySet,+ SEARCH_API_KEY_SET: searchApiKeySet,+ REMOTE_RUNTIME_RESOURCE_FACTOR: remoteRuntimeResourceFactor,+ });+ };++ const trackMcpConfigUpdated = ({+ sseServersCount,+ stdioServersCount,+ }: {+ sseServersCount: number;+ stdioServersCount: number;+ }) => {+ track("mcp_config_updated", {+ has_mcp_config: true,+ sse_servers_count: sseServersCount,+ stdio_servers_count: stdioServersCount,+ });+ };++ const trackDownloadTrajectoryButtonClicked = () => {+ track("download_trajectory_button_clicked");+ };+return {trackLoginButtonClick,trackConversationCreated,@@ -66,5 +153,12 @@ export const useTracking = () => {trackPullButtonClick,trackCreatePrButtonClick,trackUserSignupCompleted,+ trackPrebuiltAutomationEnabled,+ trackInitialQuerySubmitted,+ trackUserMessageSent,+ trackDownloadVsCodeButtonClicked,+ trackSettingsSaved,+ trackMcpConfigUpdated,+ trackDownloadTrajectoryButtonClicked,};};diff --git a/src/routes/automation-detail.tsx b/src/routes/automation-detail.tsxindex 327e4de397..562cc96eaa 100644--- a/src/routes/automation-detail.tsx+++ b/src/routes/automation-detail.tsx@@ -29,6 +29,7 @@ import { ErrorState } from "#/components/features/automations/error-state";import { BackendNotConfigured } from "#/components/features/automations/backend-not-configured";import { DeleteConfirmationModal } from "#/components/features/automations/delete-confirmation-modal";import { EditAutomationModal } from "#/components/features/automations/detail/edit-automation-modal";+import { useTracking } from "#/hooks/use-tracking";export default function AutomationDetail() {const { t } = useTranslation("openhands");@@ -66,6 +67,7 @@ export default function AutomationDetail() {enabled: isBackendHealthy && !backendChanged,});+ const { trackPrebuiltAutomationEnabled } = useTracking();const toggleMutation = useToggleAutomation();const deleteMutation = useDeleteAutomation();const dispatchMutation = useDispatchAutomation();@@ -126,10 +128,14 @@ export default function AutomationDetail() {}const handleToggle = () => {- toggleMutation.mutate({- id: automation.id,- enabled: !automation.enabled,- });+ const willEnable = !automation.enabled;+ toggleMutation.mutate({ id: automation.id, enabled: willEnable });+ if (willEnable) {+ trackPrebuiltAutomationEnabled({+ automationId: automation.id,+ automationName: automation.name,+ });+ }};const handleDelete = () => {diff --git a/src/routes/automations-list.tsx b/src/routes/automations-list.tsxindex 7663c25bad..864a6f80df 100644--- a/src/routes/automations-list.tsx+++ b/src/routes/automations-list.tsx@@ -31,6 +31,7 @@ import { EditAutomationModal } from "#/components/features/automations/detail/edimport { AddAutomationModal } from "#/components/features/automations/add-automation-modal";import { RecommendedAutomationsLauncher } from "#/components/features/automations/recommended-automations-launcher";import { BrandButton } from "#/components/features/settings/brand-button";+import { useTracking } from "#/hooks/use-tracking";import type { Automation } from "#/types/automation";const PAGE_SIZE = 50;@@ -68,6 +69,7 @@ export default function AutomationsList() {offset: 0,enabled: isBackendHealthy,});+ const { trackPrebuiltAutomationEnabled } = useTracking();const toggleMutation = useToggleAutomation();const deleteMutation = useDeleteAutomation();const dispatchMutation = useDispatchAutomation();@@ -95,7 +97,15 @@ export default function AutomationsList() {);const handleToggle = (id: string, currentEnabled: boolean) => {- toggleMutation.mutate({ id, enabled: !currentEnabled });+ const willEnable = !currentEnabled;+ toggleMutation.mutate({ id, enabled: willEnable });+ if (willEnable) {+ const automation = data?.automations.find((a) => a.id === id);+ trackPrebuiltAutomationEnabled({+ automationId: id,+ automationName: automation?.name ?? id,+ });+ }};const handleRunNow = (id: string) => {diff --git a/src/routes/root-layout.tsx b/src/routes/root-layout.tsxindex 8c71edabdd..221e28a8dc 100644--- a/src/routes/root-layout.tsx+++ b/src/routes/root-layout.tsx@@ -15,6 +15,7 @@ import { SidebarMobileMenuBar } from "#/components/features/sidebar/sidebar-mobiimport { useSettings } from "#/hooks/query/use-settings";import { useMigrateUserConsent } from "#/hooks/use-migrate-user-consent";import { useSyncPostHogConsent } from "#/hooks/use-sync-posthog-consent";+import { usePostHogIdentify } from "#/hooks/use-posthog-identify";import { LoadingSpinner } from "#/components/shared/loading-spinner";import { useAppTitle } from "#/hooks/use-app-title";import { ReactRouterNavigationProvider } from "./react-router-navigation-provider";@@ -81,6 +82,7 @@ export default function MainApp() {const [consentFormIsOpen, setConsentFormIsOpen] = React.useState(false);useSyncPostHogConsent();+ usePostHogIdentify();React.useEffect(() => {if (settings?.language) {