Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: add posthog events for install, conversation creation, and automations (#1036)

HeyItsChloe466164808ab0
diff --git a/.env.sample b/.env.sample
index 88656258ff..00a1d81a5a 100644
--- a/.env.sample
+++ b/.env.sample
@@ -16,6 +16,11 @@ VITE_FRONTEND_PORT="3001" # Port to run the frontend application
VITE_USE_TLS="false" # Use HTTPS/WSS for proxied backend connections
VITE_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.md
index 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.ts
index 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.tsx
index 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 context
const 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 API
if (conversationId) {
diff --git a/src/components/shared/modals/settings/settings-form.tsx b/src/components/shared/modals/settings/settings-form.tsx
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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/ed
import { 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.tsx
index 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-mobi
import { 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) {