Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: emit backend_added PostHog event on user-initiated backend adds (#1548)

Hiep Le4470c5c3db71
diff --git a/__tests__/components/backends/add-backend-modal.test.tsx b/__tests__/components/backends/add-backend-modal.test.tsx
index 803fa4985b..1e28068351 100644
--- a/__tests__/components/backends/add-backend-modal.test.tsx
+++ b/__tests__/components/backends/add-backend-modal.test.tsx
@@ -21,6 +21,21 @@ vi.mock("@openhands/typescript-client/clients", () => ({
}),
}));
+// Mock the services useTracking depends on (PostHog client + settings) so the
+// consent gate is open and captured events are observable. useTracking itself
+// is never mocked.
+const captureMock = vi.hoisted(() => vi.fn());
+
+vi.mock("posthog-js/react", () => ({
+ usePostHog: () => ({ capture: captureMock }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+ useSettings: () => ({
+ data: { user_consents_to_analytics: true, email: "[email protected]" },
+ }),
+}));
+
function renderWithProviders(
ui: React.ReactElement,
navigation?: NavigationContextValue,
@@ -45,6 +60,7 @@ beforeEach(() => {
window.localStorage.clear();
getServerInfoMock.mockReset();
getServerInfoMock.mockResolvedValue({ version: "1.28.0" });
+ captureMock.mockClear();
__resetActiveStoreForTests();
});
@@ -315,3 +331,39 @@ describe("AddBackendModal – redirect after adding a backend", () => {
expect(navigate).not.toHaveBeenCalled();
});
});
+
+describe("AddBackendModal – analytics", () => {
+ it("captures backend_added once with manual connection metadata", async () => {
+ // Arrange
+ renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+ const user = userEvent.setup();
+
+ // Act β€” connect a local backend through the manual form
+ await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+ await user.type(
+ screen.getByTestId("add-backend-host"),
+ "http://localhost:8000",
+ );
+ await user.type(screen.getByTestId("add-backend-api-key"), "sk-local");
+ await user.click(screen.getByTestId("add-backend-submit"));
+
+ // Assert β€” emitted exactly once with coarse, non-sensitive properties
+ await waitFor(() =>
+ expect(captureMock).toHaveBeenCalledWith(
+ "backend_added",
+ expect.objectContaining({
+ backend_kind: "local",
+ connection_method: "manual",
+ is_openhands_cloud: false,
+ is_custom_host: true,
+ has_api_key: true,
+ source: "add_backend_modal",
+ }),
+ ),
+ );
+ const backendAddedCalls = captureMock.mock.calls.filter(
+ ([event]) => event === "backend_added",
+ );
+ expect(backendAddedCalls).toHaveLength(1);
+ });
+});
diff --git a/__tests__/components/backends/manage-backends-modal.test.tsx b/__tests__/components/backends/manage-backends-modal.test.tsx
index a4c214f2bf..b3a42ed083 100644
--- a/__tests__/components/backends/manage-backends-modal.test.tsx
+++ b/__tests__/components/backends/manage-backends-modal.test.tsx
@@ -62,6 +62,21 @@ vi.mock("#/api/device-flow-client", () => ({
},
}));
+// Mock the services useTracking depends on (PostHog client + settings) so the
+// consent gate is open and captured events are observable. useTracking itself
+// is never mocked.
+const captureMock = vi.hoisted(() => vi.fn());
+
+vi.mock("posthog-js/react", () => ({
+ usePostHog: () => ({ capture: captureMock }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+ useSettings: () => ({
+ data: { user_consents_to_analytics: true, email: "[email protected]" },
+ }),
+}));
+
function renderWithProviders(ui: React.ReactElement) {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
@@ -121,6 +136,7 @@ beforeEach(() => {
});
deviceFlowMocks.pollForToken.mockReset();
deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => {}));
+ captureMock.mockClear();
__resetActiveStoreForTests();
__resetHealthStoreForTests();
});
@@ -483,6 +499,66 @@ describe("ManageBackendsModal", () => {
screen.queryByTestId("manage-backends-org-Acme Local"),
).not.toBeInTheDocument();
});
+
+ it("captures backend_added with source manage_backends_modal when adding from here", async () => {
+ const user = userEvent.setup();
+ renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+ await user.click(await screen.findByTestId("manage-backends-add"));
+ await screen.findByTestId("add-backend-modal");
+
+ await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+ await user.type(
+ screen.getByTestId("add-backend-host"),
+ "http://localhost:8000",
+ );
+ await user.type(screen.getByTestId("add-backend-api-key"), "sk-local");
+ await user.click(screen.getByTestId("add-backend-submit"));
+
+ await waitFor(() =>
+ expect(captureMock).toHaveBeenCalledWith(
+ "backend_added",
+ expect.objectContaining({ source: "manage_backends_modal" }),
+ ),
+ );
+ });
+
+ it("does not capture backend_added when editing an existing backend", async () => {
+ const user = userEvent.setup();
+ renderWithProviders(
+ <TestSeed
+ onMount={(ctx) => {
+ ctx.addBackend({
+ name: "Acme Local",
+ host: "http://localhost:9000",
+ apiKey: "old-key",
+ kind: "local",
+ });
+ }}
+ >
+ <ManageBackendsModal onClose={vi.fn()} />
+ </TestSeed>,
+ );
+
+ await user.click(
+ await screen.findByTestId("manage-backends-edit-Acme Local"),
+ );
+ await screen.findByTestId("edit-backend-modal");
+ const hostInput = screen.getByTestId("edit-backend-host");
+ await user.clear(hostInput);
+ await user.type(hostInput, "http://localhost:9999");
+ await user.click(screen.getByTestId("edit-backend-submit"));
+
+ await waitFor(() =>
+ expect(
+ screen.queryByTestId("edit-backend-modal"),
+ ).not.toBeInTheDocument(),
+ );
+ expect(captureMock).not.toHaveBeenCalledWith(
+ "backend_added",
+ expect.anything(),
+ );
+ });
});
function renderInQueryClient(ui: React.ReactElement) {
diff --git a/__tests__/hooks/use-tracking.test.ts b/__tests__/hooks/use-tracking.test.ts
index 118d84eb5b..7984dc0c06 100644
--- a/__tests__/hooks/use-tracking.test.ts
+++ b/__tests__/hooks/use-tracking.test.ts
@@ -239,6 +239,29 @@ describe("useTracking", () => {
});
});
+ describe("trackBackendAdded", () => {
+ it("captures backend_added with coarse, non-sensitive backend metadata", () => {
+ getTracking().trackBackendAdded({
+ backendKind: "cloud",
+ connectionMethod: "cloud_login",
+ isOpenhandsCloud: true,
+ isCustomHost: false,
+ hasApiKey: true,
+ source: "add_backend_modal",
+ });
+
+ expect(captureMock).toHaveBeenCalledWith("backend_added", {
+ backend_kind: "cloud",
+ connection_method: "cloud_login",
+ is_openhands_cloud: true,
+ is_custom_host: false,
+ has_api_key: true,
+ source: "add_backend_modal",
+ ...COMMON,
+ });
+ });
+ });
+
describe("consent gate", () => {
it("does not capture when posthog is not initialized", () => {
posthogMock = undefined;
diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsx
index 3a6fa84526..43a0b6b0c7 100644
--- a/src/components/features/backends/backend-form-modal.tsx
+++ b/src/components/features/backends/backend-form-modal.tsx
@@ -14,6 +14,7 @@ import { SettingsInput } from "#/components/features/settings/settings-input";
import { useActiveBackendContext } from "#/contexts/active-backend-context";
import { useNavigation } from "#/context/navigation-context";
import { useBackendsHealth } from "#/hooks/query/use-backends-health";
+import { useTracking } from "#/hooks/use-tracking";
import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
import { getLockedCloudHost } from "#/api/agent-server-config";
import {
@@ -40,6 +41,8 @@ interface BackendFormModalProps {
/** Required when `mode === "edit"`. */
backend?: Backend;
onClose: () => void;
+ /** Analytics surface for the `backend_added` event (add mode only). */
+ source?: BackendAddedSource;
}
function inferKindFromHost(host: string): BackendKind {
@@ -125,6 +128,10 @@ function isValidHostUrl(host: string): boolean {
const DEFAULT_OPENHANDS_CLOUD_HOST = "https://app.all-hands.dev";
+export type BackendConnectionMethod = "manual" | "cloud_login";
+
+export type BackendAddedSource = "add_backend_modal" | "manage_backends_modal";
+
function getConnectionTestFailedTitle(
t: ReturnType<typeof useTranslation>["t"],
host: string,
@@ -663,7 +670,10 @@ function useRedirectAfterAddBackend() {
}
interface BackendConnectionOptionsProps {
- onConnected: (payload: BackendFormSubmitPayload) => void;
+ onConnected: (
+ payload: BackendFormSubmitPayload,
+ connectionMethod: BackendConnectionMethod,
+ ) => void;
testIdRoot?: string;
initialManualBackend?: Partial<
Pick<BackendFormSubmitPayload, "name" | "host" | "apiKey">
@@ -736,7 +746,10 @@ export function BackendConnectionOptions({
}
interface ManualConnectionColumnProps {
- onConnected: (payload: BackendFormSubmitPayload) => void;
+ onConnected: (
+ payload: BackendFormSubmitPayload,
+ connectionMethod: BackendConnectionMethod,
+ ) => void;
testIdRoot: string;
initialBackend?: Partial<
Pick<BackendFormSubmitPayload, "name" | "host" | "apiKey">
@@ -781,12 +794,15 @@ function ManualConnectionColumn({
initialApiKey: initialBackend?.apiKey ?? "",
onTestConnection: testBackendConnection,
onSuccess: () => {
- onConnected({
- name: name.trim(),
- host: normalizeHost(host),
- apiKey: apiKey.trim(),
- kind,
- });
+ onConnected(
+ {
+ name: name.trim(),
+ host: normalizeHost(host),
+ apiKey: apiKey.trim(),
+ kind,
+ },
+ "manual",
+ );
},
requireApiKey,
});
@@ -879,7 +895,10 @@ function ManualConnectionColumn({
}
interface CloudLoginColumnProps {
- onConnected: (payload: BackendFormSubmitPayload) => void;
+ onConnected: (
+ payload: BackendFormSubmitPayload,
+ connectionMethod: BackendConnectionMethod,
+ ) => void;
testIdRoot: string;
lockedHost?: string;
}
@@ -903,12 +922,15 @@ function CloudLoginColumn({
lockedHost ?? (customHost.trim() || DEFAULT_OPENHANDS_CLOUD_HOST);
const handleLoginSuccess = (apiKey: string) => {
- onConnected({
- name: "OpenHands Cloud",
- host: normalizeHost(effectiveHost),
- apiKey,
- kind: "cloud",
- });
+ onConnected(
+ {
+ name: "OpenHands Cloud",
+ host: normalizeHost(effectiveHost),
+ apiKey,
+ kind: "cloud",
+ },
+ "cloud_login",
+ );
};
return (
@@ -979,17 +1001,37 @@ function CloudLoginColumn({
);
}
-function AddBackendConnectionOptions({ onClose }: { onClose: () => void }) {
+function AddBackendConnectionOptions({
+ onClose,
+ source,
+}: {
+ onClose: () => void;
+ source: BackendAddedSource;
+}) {
const { addBackend } = useActiveBackendContext();
const redirectAfterAdd = useRedirectAfterAddBackend();
+ const { trackBackendAdded } = useTracking();
const handleConnected = React.useCallback(
- (payload: BackendFormSubmitPayload) => {
+ (
+ payload: BackendFormSubmitPayload,
+ connectionMethod: BackendConnectionMethod,
+ ) => {
addBackend(payload);
+ // Coarse, non-sensitive host classification β€” never emit the raw host.
+ const isOpenHandsCloud = payload.host === DEFAULT_OPENHANDS_CLOUD_HOST;
+ trackBackendAdded({
+ backendKind: payload.kind,
+ connectionMethod,
+ isOpenhandsCloud: isOpenHandsCloud,
+ isCustomHost: !isOpenHandsCloud,
+ hasApiKey: Boolean(payload.apiKey),
+ source,
+ });
redirectAfterAdd();
onClose();
},
- [addBackend, redirectAfterAdd, onClose],
+ [addBackend, redirectAfterAdd, onClose, trackBackendAdded, source],
);
return <BackendConnectionOptions onConnected={handleConnected} />;
@@ -1006,6 +1048,7 @@ export function BackendFormModal({
mode,
backend,
onClose,
+ source = "add_backend_modal",
}: BackendFormModalProps) {
const { t } = useTranslation("openhands");
@@ -1033,7 +1076,7 @@ export function BackendFormModal({
</div>
<div className="px-6 pb-6 pt-2">
- <AddBackendConnectionOptions onClose={onClose} />
+ <AddBackendConnectionOptions onClose={onClose} source={source} />
</div>
</div>
</ModalBackdrop>
diff --git a/src/components/features/backends/manage-backends-modal.tsx b/src/components/features/backends/manage-backends-modal.tsx
index 3de5fce168..0be04a6300 100644
--- a/src/components/features/backends/manage-backends-modal.tsx
+++ b/src/components/features/backends/manage-backends-modal.tsx
@@ -193,7 +193,11 @@ export function ManageBackendsModal({
</ModalBackdrop>
{showAddForm ? (
- <BackendFormModal mode="add" onClose={() => setShowAddForm(false)} />
+ <BackendFormModal
+ mode="add"
+ source="manage_backends_modal"
+ onClose={() => setShowAddForm(false)}
+ />
) : null}
{editingBackend ? (
diff --git a/src/hooks/use-tracking.ts b/src/hooks/use-tracking.ts
index d3699c4e74..438017463e 100644
--- a/src/hooks/use-tracking.ts
+++ b/src/hooks/use-tracking.ts
@@ -1,6 +1,7 @@
import { usePostHog } from "posthog-js/react";
import { useSettings } from "./query/use-settings";
import { Provider } from "#/types/settings";
+import type { BackendKind } from "#/api/backend-registry/types";
/**
* Hook that provides tracking functions with automatic data collection
@@ -146,6 +147,31 @@ export const useTracking = () => {
track("download_trajectory_button_clicked");
};
+ const trackBackendAdded = ({
+ backendKind,
+ connectionMethod,
+ isOpenhandsCloud,
+ isCustomHost,
+ hasApiKey,
+ source,
+ }: {
+ backendKind: BackendKind;
+ connectionMethod: "manual" | "cloud_login";
+ isOpenhandsCloud: boolean;
+ isCustomHost: boolean;
+ hasApiKey: boolean;
+ source?: "add_backend_modal" | "manage_backends_modal";
+ }) => {
+ track("backend_added", {
+ backend_kind: backendKind,
+ connection_method: connectionMethod,
+ is_openhands_cloud: isOpenhandsCloud,
+ is_custom_host: isCustomHost,
+ has_api_key: hasApiKey,
+ source,
+ });
+ };
+
const trackOnboardingStarted = () => {
track("onboarding_started");
};
@@ -206,6 +232,7 @@ export const useTracking = () => {
trackSettingsSaved,
trackMcpConfigUpdated,
trackDownloadTrajectoryButtonClicked,
+ trackBackendAdded,
trackOnboardingStarted,
trackOnboardingStepViewed,
trackOnboardingCompleted,