Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: instrument onboarding checklist link clicks (#16777)

Hiep Le56227de5e405
diff --git a/AGENTS.md b/AGENTS.md
index 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` object
3. 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.tsx
index 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.ts
index 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.tsx
index 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.ts
index 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.tsx
index 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={
<SidebarOnboardingChecklistItemPreview
id={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.ts
index 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,
};
};