π OpenHands: AI-Driven Development
feat: instrument onboarding checklist link clicks (#16777)
Hiep Le56227de5e405
diff --git a/AGENTS.md b/AGENTS.mdindex 13e724cc79..8cb0969320 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -74,6 +74,54 @@ One Canvas-owned PostHog client owns telemetry and app analytics.2. Add the function to the hook's `return` object3. Destructure and call it from the component: `const { trackFoo } = useTracking()`+### Event dictionary: onboarding_link_clicked++One stable event for every onboarding link/CTA click. New onboarding links must+reuse this contract (extend the unions in `use-tracking.ts`), never add one-off+events per destination.++Properties (all values controlled enums or booleans β never raw destination+URLs, query params, or link text; `current_url` is the standard app-page common+property, not a destination):+- `link_id` (`OnboardingLinkId`): `configure_llm` | `start_conversation` |+ `schedule_task` | `customize_agent` | `connect_mcp` | `join_slack` |+ `open_docs`+- `destination_type` (`OnboardingLinkDestinationType`): `community` |+ `integration` | `documentation` | `settings` | `conversation` | `automation`+- `surface` (`OnboardingLinkSurface`): `landing_checklist` |+ `onboarding_modal` (reserved; no modal links are instrumented yet)+- `checklist_item` (optional): the owning checklist item's `link_id`; set on+ every `landing_checklist` emission, including `open_docs` clicks+- `step_id` (optional): reserved for future onboarding-modal links+- `is_external` (boolean): whether the destination leaves the app++Instrumented CTAs (sidebar "Getting started" checklist; the row link and its+preview action CTA intentionally share one `link_id` β same destination):++| Checklist item | Row + preview action | Preview docs link |+|---|---|---|+| Add LLM API key | `configure_llm` / `settings` / internal | `open_docs` / `documentation` / external |+| Start your first chat | `start_conversation` / `conversation` / internal | `open_docs` |+| Schedule a task | `schedule_task` / `automation` / internal | `open_docs` |+| Customize your agent | `customize_agent` / `settings` / internal | `open_docs` |+| Connect an MCP integration | `connect_mcp` / `integration` / internal | `open_docs` |+| Join the OpenHands Slack | `join_slack` / `community` / external | `open_docs` |++Excluded CTAs (per the one-canonical-capture rule above):+- Onboarding-modal wizard controls (back/next/skip/close, agent cards) β+ covered by `onboarding_step_viewed` / `onboarding_completed` /+ `onboarding_skipped`+- Modal backend-connect CTAs and the backend form's docs links β+ `backend_added` with `source: "onboarding"`+- LLM settings help links inside the embedded settings screen (shared with+ non-onboarding surfaces) β setup outcome captured by `settings_saved`+- Recommended-automation cards β `prebuilt_automation_enabled`+- Checklist expand/collapse toggle and the settings visibility switch β UI+ state, not destination links++Known limitation: middle-click (`auxclick`) opens are not captured; tracking+uses React `onClick` only and never prevents default navigation.+### Env vars`VITE_POSTHOG_API_KEY` is the sole build-time PostHog key. Unconfigured source builds use staging; official release workflows set production explicitly. Precompiled consumers use runtime configuration instead.diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsxindex 1fd438bedb..46e3eadade 100644--- a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx@@ -1,4 +1,12 @@-import { beforeEach, describe, expect, it, vi } from "vitest";+import {+ afterEach,+ beforeEach,+ describe,+ expect,+ it,+ type MockInstance,+ vi,+} from "vitest";import { render, screen } from "@testing-library/react";import userEvent from "@testing-library/user-event";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";@@ -19,6 +27,7 @@ import {type NavigationContextValue,} from "#/context/navigation-context";import { I18nKey } from "#/i18n/declaration";+import * as telemetry from "#/services/telemetry";const mockUsePaginatedConversations = vi.fn();const mockUseAutomationHealth = vi.fn();@@ -55,20 +64,24 @@ function renderChecklist() {const queryClient = new QueryClient({defaultOptions: { queries: { retry: false }, mutations: { retry: false } },});+ const navigate = vi.fn();const navigation: NavigationContextValue = {currentPath: "/",conversationId: null,isNavigating: false,- navigate: vi.fn(),+ navigate,};- return render(- <QueryClientProvider client={queryClient}>- <NavigationProvider value={navigation}>- <SidebarOnboardingChecklist collapsed={false} />- </NavigationProvider>- </QueryClientProvider>,- );+ return {+ ...render(+ <QueryClientProvider client={queryClient}>+ <NavigationProvider value={navigation}>+ <SidebarOnboardingChecklist collapsed={false} />+ </NavigationProvider>+ </QueryClientProvider>,+ ),+ navigate,+ };}describe("SidebarOnboardingChecklist", () => {@@ -285,4 +298,108 @@ describe("SidebarOnboardingChecklist", () => {screen.queryByTestId("sidebar-onboarding-checklist"),).not.toBeInTheDocument();});++ describe("onboarding link tracking", () => {+ let captureMock: MockInstance<typeof telemetry.trackEvent>;++ beforeEach(() => {+ captureMock = vi+ .spyOn(telemetry, "trackEvent")+ .mockResolvedValue(undefined);+ });++ afterEach(() => {+ captureMock.mockRestore();+ });++ const linkClickEvents = () =>+ captureMock.mock.calls.filter(+ ([name]) => name === "onboarding_link_clicked",+ );++ it("captures a single onboarding_link_clicked when the Join Slack row is clicked", async () => {+ const user = userEvent.setup();+ renderChecklist();++ await user.click(+ screen.getByTestId("sidebar-onboarding-checklist-item-join-slack"),+ );++ expect(linkClickEvents()).toHaveLength(1);+ expect(linkClickEvents()[0][1]).toMatchObject({+ link_id: "join_slack",+ destination_type: "community",+ surface: "landing_checklist",+ checklist_item: "join_slack",+ is_external: true,+ });+ });++ it("captures onboarding_link_clicked for an internal row and still navigates", async () => {+ const user = userEvent.setup();+ const { navigate } = renderChecklist();++ await user.click(+ screen.getByTestId("sidebar-onboarding-checklist-item-configure-llm"),+ );++ expect(linkClickEvents()).toHaveLength(1);+ expect(linkClickEvents()[0][1]).toMatchObject({+ link_id: "configure_llm",+ destination_type: "settings",+ surface: "landing_checklist",+ checklist_item: "configure_llm",+ is_external: false,+ });+ expect(navigate).toHaveBeenCalledWith("/settings/llm", {+ replace: false,+ });+ });++ it("captures open_docs with the owning checklist item when a preview docs link is clicked", async () => {+ const user = userEvent.setup();+ renderChecklist();++ await user.hover(+ screen.getByTestId("sidebar-onboarding-checklist-item-connect-mcp"),+ );+ await user.click(+ await screen.findByTestId(+ "sidebar-onboarding-checklist-preview-docs-connect-mcp",+ ),+ );++ expect(linkClickEvents()).toHaveLength(1);+ expect(linkClickEvents()[0][1]).toMatchObject({+ link_id: "open_docs",+ destination_type: "documentation",+ surface: "landing_checklist",+ checklist_item: "connect_mcp",+ is_external: true,+ });+ });++ it("captures the row's link_id when a preview action CTA is clicked", async () => {+ const user = userEvent.setup();+ renderChecklist();++ await user.hover(+ screen.getByTestId("sidebar-onboarding-checklist-item-schedule-task"),+ );+ await user.click(+ await screen.findByTestId(+ "sidebar-onboarding-checklist-preview-action-schedule-task",+ ),+ );++ expect(linkClickEvents()).toHaveLength(1);+ expect(linkClickEvents()[0][1]).toMatchObject({+ link_id: "schedule_task",+ destination_type: "automation",+ surface: "landing_checklist",+ checklist_item: "schedule_task",+ is_external: false,+ });+ });+ });});diff --git a/__tests__/hooks/use-tracking.test.ts b/__tests__/hooks/use-tracking.test.tsindex 9ce89e22bd..66fdfd88a6 100644--- a/__tests__/hooks/use-tracking.test.ts+++ b/__tests__/hooks/use-tracking.test.ts@@ -420,6 +420,28 @@ describe("useTracking", () => {});});+ describe("trackOnboardingLinkClicked", () => {+ it("captures onboarding_link_clicked with the typed link contract and commonProperties", () => {+ getTracking().trackOnboardingLinkClicked({+ linkId: "join_slack",+ destinationType: "community",+ surface: "landing_checklist",+ checklistItem: "join_slack",+ isExternal: true,+ });++ expect(captureMock).toHaveBeenCalledWith("onboarding_link_clicked", {+ link_id: "join_slack",+ destination_type: "community",+ surface: "landing_checklist",+ checklist_item: "join_slack",+ step_id: undefined,+ is_external: true,+ ...COMMON,+ });+ });+ });+describe("shared telemetry boundary", () => {it("delegates consent enforcement when backend settings report false", () => {useSettingsMock.mockReturnValue({diff --git a/src/components/features/sidebar/sidebar-onboarding-checklist-item-preview.tsx b/src/components/features/sidebar/sidebar-onboarding-checklist-item-preview.tsxindex 047c65dc60..097b4f7661 100644--- a/src/components/features/sidebar/sidebar-onboarding-checklist-item-preview.tsx+++ b/src/components/features/sidebar/sidebar-onboarding-checklist-item-preview.tsx@@ -21,11 +21,13 @@ const PREVIEW_ACTION_BUTTON_CLASS = cn(interface SidebarOnboardingChecklistItemPreviewProps {id: SidebarOnboardingChecklistItemId;onActionClick?: () => void;+ onDocsClick?: () => void;}export function SidebarOnboardingChecklistItemPreview({id,onActionClick,+ onDocsClick,}: SidebarOnboardingChecklistItemPreviewProps) {const { t } = useTranslation("openhands");const titleKey = SIDEBAR_ONBOARDING_CHECKLIST_I18N_KEYS[id];@@ -57,6 +59,7 @@ export function SidebarOnboardingChecklistItemPreview({rel="noreferrer"data-testid={`sidebar-onboarding-checklist-preview-docs-${id}`}className="inline-flex min-w-0 items-center gap-2 text-xs text-[var(--oh-muted)] transition-colors hover:text-white hover:underline"+ onClick={onDocsClick}><BookOpen className="size-3.5 shrink-0" aria-hidden />{t(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_DOCS_LINK)}@@ -77,6 +80,7 @@ export function SidebarOnboardingChecklistItemPreview({to={href.href}data-testid={`sidebar-onboarding-checklist-preview-action-${id}`}className={PREVIEW_ACTION_BUTTON_CLASS}+ onClick={onActionClick}>{t(actionKey)}</NavigationLink>diff --git a/src/components/features/sidebar/sidebar-onboarding-checklist.constants.ts b/src/components/features/sidebar/sidebar-onboarding-checklist.constants.tsindex 695b62a472..e6059f80d5 100644--- a/src/components/features/sidebar/sidebar-onboarding-checklist.constants.ts+++ b/src/components/features/sidebar/sidebar-onboarding-checklist.constants.ts@@ -1,4 +1,8 @@import { I18nKey } from "#/i18n/declaration";+import type {+ OnboardingLinkDestinationType,+ OnboardingLinkId,+} from "#/hooks/use-tracking";const SCHEDULED_TASKS_DOCS_URL ="https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations";@@ -49,6 +53,31 @@ export const SIDEBAR_ONBOARDING_CHECKLIST_ROUTES: Record<"customize-agent": "/settings/agents",};+/** Semantic `link_id` values for `onboarding_link_clicked` (no `open_docs`). */+export const SIDEBAR_ONBOARDING_CHECKLIST_LINK_IDS: Record<+ SidebarOnboardingChecklistItemId,+ Exclude<OnboardingLinkId, "open_docs">+> = {+ "configure-llm": "configure_llm",+ "start-conversation": "start_conversation",+ "schedule-task": "schedule_task",+ "customize-agent": "customize_agent",+ "connect-mcp": "connect_mcp",+ "join-slack": "join_slack",+};++export const SIDEBAR_ONBOARDING_CHECKLIST_DESTINATION_TYPES: Record<+ SidebarOnboardingChecklistItemId,+ OnboardingLinkDestinationType+> = {+ "configure-llm": "settings",+ "start-conversation": "conversation",+ "schedule-task": "automation",+ "customize-agent": "settings",+ "connect-mcp": "integration",+ "join-slack": "community",+};+export function isExternalSidebarOnboardingChecklistItem(id: SidebarOnboardingChecklistItemId,): id is "join-slack" {diff --git a/src/components/features/sidebar/sidebar-onboarding-checklist.tsx b/src/components/features/sidebar/sidebar-onboarding-checklist.tsxindex 2445e34e0d..ae54a1a5ae 100644--- a/src/components/features/sidebar/sidebar-onboarding-checklist.tsx+++ b/src/components/features/sidebar/sidebar-onboarding-checklist.tsx@@ -2,12 +2,15 @@ import { Tooltip } from "@heroui/react";import { Check, ChevronDown } from "lucide-react";import { useTranslation } from "react-i18next";import { NavigationLink } from "#/components/shared/navigation-link";+import { useTracking } from "#/hooks/use-tracking";import { I18nKey } from "#/i18n/declaration";import { cn } from "#/utils/utils";import {getSidebarOnboardingChecklistHref,isExternalSidebarOnboardingChecklistItem,+ SIDEBAR_ONBOARDING_CHECKLIST_DESTINATION_TYPES,SIDEBAR_ONBOARDING_CHECKLIST_I18N_KEYS,+ SIDEBAR_ONBOARDING_CHECKLIST_LINK_IDS,type SidebarOnboardingChecklistItemId,} from "./sidebar-onboarding-checklist.constants";import { SidebarOnboardingChecklistItemPreview } from "./sidebar-onboarding-checklist-item-preview";@@ -51,9 +54,33 @@ function ChecklistItem({onActivate?: () => void;}) {const { t } = useTranslation("openhands");+ const { trackOnboardingLinkClicked } = useTracking();const labelKey = SIDEBAR_ONBOARDING_CHECKLIST_I18N_KEYS[id];const disableAnimation = import.meta.env.MODE === "test";const href = getSidebarOnboardingChecklistHref(id);+ const linkId = SIDEBAR_ONBOARDING_CHECKLIST_LINK_IDS[id];++ const handleLinkClick = () => {+ trackOnboardingLinkClicked({+ linkId,+ destinationType: SIDEBAR_ONBOARDING_CHECKLIST_DESTINATION_TYPES[id],+ surface: "landing_checklist",+ checklistItem: linkId,+ isExternal: href.kind === "external",+ });+ onActivate?.();+ };++ const handleDocsClick = () => {+ trackOnboardingLinkClicked({+ linkId: "open_docs",+ destinationType: "documentation",+ surface: "landing_checklist",+ checklistItem: linkId,+ isExternal: true,+ });+ };+const itemClassName = cn(CHECKLIST_ITEM_CLASS,isComplete ? "text-muted" : "text-content",@@ -80,7 +107,8 @@ function ChecklistItem({content={<SidebarOnboardingChecklistItemPreviewid={id}- onActionClick={onActivate}+ onActionClick={handleLinkClick}+ onDocsClick={handleDocsClick}/>}>@@ -91,7 +119,7 @@ function ChecklistItem({rel="noreferrer"data-testid={`sidebar-onboarding-checklist-item-${id}`}className={itemClassName}- onClick={onActivate}+ onClick={handleLinkClick}>{label}</a>@@ -100,6 +128,7 @@ function ChecklistItem({to={href.href}data-testid={`sidebar-onboarding-checklist-item-${id}`}className={itemClassName}+ onClick={handleLinkClick}>{label}</NavigationLink>diff --git a/src/hooks/use-tracking.ts b/src/hooks/use-tracking.tsindex fa89acc8ab..03a94dc76e 100644--- a/src/hooks/use-tracking.ts+++ b/src/hooks/use-tracking.ts@@ -12,6 +12,31 @@ import {} from "#/services/telemetry-context";import { setTelemetryBackendContext, trackEvent } from "#/services/telemetry";+/**+ * Stable semantic identifier for an onboarding link or CTA. Identifies the+ * destination, never the clicked element or its text.+ */+export type OnboardingLinkId =+ | "configure_llm"+ | "start_conversation"+ | "schedule_task"+ | "customize_agent"+ | "connect_mcp"+ | "join_slack"+ | "open_docs";++/** Controlled destination category for `onboarding_link_clicked`. */+export type OnboardingLinkDestinationType =+ | "community"+ | "integration"+ | "documentation"+ | "settings"+ | "conversation"+ | "automation";++/** Onboarding surface that presented the link. */+export type OnboardingLinkSurface = "landing_checklist" | "onboarding_modal";+/*** Hook that provides tracking functions with automatic data collection* from available hooks (settings, etc.)@@ -411,6 +436,31 @@ export const useTracking = () => {});};+ const trackOnboardingLinkClicked = ({+ linkId,+ destinationType,+ surface,+ checklistItem,+ stepId,+ isExternal,+ }: {+ linkId: OnboardingLinkId;+ destinationType: OnboardingLinkDestinationType;+ surface: OnboardingLinkSurface;+ checklistItem?: Exclude<OnboardingLinkId, "open_docs">;+ stepId?: string;+ isExternal: boolean;+ }) => {+ track("onboarding_link_clicked", {+ link_id: linkId,+ destination_type: destinationType,+ surface,+ checklist_item: checklistItem,+ step_id: stepId,+ is_external: isExternal,+ });+ };+return {trackLoginButtonClick,trackConversationCreated,@@ -445,5 +495,6 @@ export const useTracking = () => {trackOnboardingStepViewed,trackOnboardingCompleted,trackOnboardingSkipped,+ trackOnboardingLinkClicked,};};