Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

chore: metric for onboarding guide

ecmadaoea223e2e7069
diff --git a/frontend/src/app/analytics/behavior.ts b/frontend/src/app/analytics/behavior.ts
index 8b8d5e0ded..f7399a6365 100644
--- a/frontend/src/app/analytics/behavior.ts
+++ b/frontend/src/app/analytics/behavior.ts
@@ -26,7 +26,14 @@ export type BehaviorMetricName =
| "instance create clicked"
| "locked feature clicked"
| "sample instance requested"
+ | "workspace setup page entered"
| "workspace setup submitted"
+ | "workspace setup guide opened"
+ | "workspace setup guide progress observed"
+ | "workspace setup guide step action selected"
+ | "workspace setup guide step completed"
+ | "workspace setup guide completed"
+ | "workspace setup guide dismissed"
| "post sync first change clicked"
| "post sync sql editor clicked";
diff --git a/frontend/src/components/header/ProfileMenuTrigger.test.tsx b/frontend/src/components/header/ProfileMenuTrigger.test.tsx
index a9916769d5..d864ef1b29 100644
--- a/frontend/src/components/header/ProfileMenuTrigger.test.tsx
+++ b/frontend/src/components/header/ProfileMenuTrigger.test.tsx
@@ -302,7 +302,7 @@ describe("ProfileMenuTrigger", () => {
unmount();
});
- test("resumes the selected guide", () => {
+ test("records a selected guide opening", () => {
const { container, render, unmount } = renderIntoContainer(
<ProfileMenuTrigger size="medium" link />
);
@@ -315,11 +315,18 @@ describe("ProfileMenuTrigger", () => {
expect(gettingStartedButton).not.toBeUndefined();
act(() => gettingStartedButton?.click());
expect(mocks.resumeQuickstart).toHaveBeenCalledTimes(1);
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide opened",
+ properties: {
+ journey: "query-data",
+ scenario: "query-data",
+ collaboration_type: "unselected",
+ },
+ });
unmount();
});
- test("resumes the generic setup journey without scenario analytics", () => {
+ test("records a generic guide opening", () => {
mocks.scenarioId = undefined;
const { container, render, unmount } = renderIntoContainer(
<ProfileMenuTrigger size="medium" link />
@@ -332,7 +339,14 @@ describe("ProfileMenuTrigger", () => {
).find((button) => button.textContent === "Getting started");
act(() => gettingStartedButton?.click());
expect(mocks.resumeQuickstart).toHaveBeenCalledTimes(1);
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide opened",
+ properties: {
+ journey: "workspace-setup",
+ scenario: "unselected",
+ collaboration_type: "unselected",
+ },
+ });
unmount();
});
diff --git a/frontend/src/components/header/ProfileMenuTrigger.tsx b/frontend/src/components/header/ProfileMenuTrigger.tsx
index e348a0b541..d2e080f978 100644
--- a/frontend/src/components/header/ProfileMenuTrigger.tsx
+++ b/frontend/src/components/header/ProfileMenuTrigger.tsx
@@ -1,6 +1,8 @@
import { ChevronRight } from "lucide-react";
import { useMemo, useState } from "react";
import { useTranslation } from "react-i18next";
+import { createBehaviorMetric } from "@/app/analytics/behavior";
+import { behaviorAnalytics } from "@/app/analytics/provider";
import {
ACCOUNT_ROUTE,
isSqlEditorRouteName,
@@ -239,6 +241,15 @@ export function ProfileMenuTrigger({
{workspaceSetupGuideEnabled ? (
<DropdownMenuItem
onClick={() => {
+ behaviorAnalytics.captureMetric(
+ createBehaviorMetric("workspace setup guide opened", {
+ properties: {
+ journey: journey.id,
+ scenario: scenarioId ?? "unselected",
+ collaboration_type: workspaceUsage ?? "unselected",
+ },
+ })
+ );
resumeWorkspaceSetupGuide();
setOpen(false);
}}
diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
index 5ff775d1fc..75941540fe 100644
--- a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
@@ -269,9 +269,9 @@ describe("WorkspaceSetupGuide", () => {
"setup-step-connect-instance",
"setup-step-explore-database",
"setup-step-query-data",
- "setup-step-add-teammate",
+ "setup-step-add-member",
]);
- expect(screen.getByTestId("setup-step-add-teammate")).toBeEnabled();
+ expect(screen.getByTestId("setup-step-add-member")).toBeEnabled();
});
test("acknowledges a completed multi-member team journey when closed", () => {
@@ -309,7 +309,7 @@ describe("WorkspaceSetupGuide", () => {
});
render(<WorkspaceSetupGuide />);
- fireEvent.click(screen.getByTestId("setup-step-add-teammate"));
+ fireEvent.click(screen.getByTestId("setup-step-add-member"));
expect(mocks.routerPush).toHaveBeenCalledWith({
name: "workspace.users",
@@ -329,7 +329,7 @@ describe("WorkspaceSetupGuide", () => {
});
render(<WorkspaceSetupGuide />);
- fireEvent.click(screen.getByTestId("setup-step-add-teammate"));
+ fireEvent.click(screen.getByTestId("setup-step-add-member"));
expect(mocks.routerPush).toHaveBeenCalledWith({
name: "workspace.members",
@@ -350,7 +350,7 @@ describe("WorkspaceSetupGuide", () => {
});
render(<WorkspaceSetupGuide />);
- fireEvent.click(screen.getByTestId("setup-step-add-teammate"));
+ fireEvent.click(screen.getByTestId("setup-step-add-member"));
expect(mocks.routerPush).toHaveBeenCalledWith({
name: "workspace.members",
@@ -543,22 +543,73 @@ describe("WorkspaceSetupGuide", () => {
);
});
- test("routes generic actions without recording guide analytics", () => {
+ test("records a selected guide step action", () => {
render(<WorkspaceSetupGuide />);
+ mocks.captureMetric.mockClear();
fireEvent.click(screen.getByTestId("setup-step-create-project"));
expect(mocks.routerPush).toHaveBeenCalled();
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide step action selected",
+ properties: {
+ journey: "workspace-setup",
+ scenario: "unselected",
+ collaboration_type: "unselected",
+ completed_steps: [],
+ completed_step_count: 0,
+ total_step_count: 3,
+ next_step: "create-project",
+ step: "create-project",
+ action_type: "navigate",
+ },
+ });
+ });
+
+ test("records the active SQL Editor action", () => {
+ mocks.scenarioId = "query-data";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ });
+ render(<WorkspaceSetupGuide />);
+ mocks.captureMetric.mockClear();
+
+ fireEvent.click(screen.getByTestId("active-action"));
+
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide step action selected",
+ properties: {
+ journey: "query-data",
+ scenario: "query-data",
+ collaboration_type: "unselected",
+ completed_steps: [
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ ],
+ completed_step_count: 3,
+ total_step_count: 4,
+ next_step: "query-data",
+ step: "query-data",
+ action_type: "open-sql-editor",
+ },
+ });
});
- test("dismisses the selected guide without recording analytics", () => {
+ test("records final progress when selected guide dismissed", () => {
mocks.scenarioId = "create-database-change";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
});
render(<WorkspaceSetupGuide />);
+ mocks.captureMetric.mockClear();
fireEvent.click(screen.getByTestId("dismiss-guide"));
@@ -566,7 +617,82 @@ describe("WorkspaceSetupGuide", () => {
key: GUIDE_PROGRESS_KEYS.dismissed,
newState: true,
});
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide dismissed",
+ properties: {
+ journey: "create-database-change",
+ scenario: "create-database-change",
+ collaboration_type: "unselected",
+ completed_steps: [
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ ],
+ completed_step_count: 3,
+ total_step_count: 4,
+ next_step: "create-database-change",
+ },
+ });
+ });
+
+ test("records a step completion only when guide progress changes", () => {
+ const { rerender } = render(<WorkspaceSetupGuide />);
+ mocks.captureMetric.mockClear();
+
+ mocks.guideContext = guideContext({ hasProject: true });
+ rerender(<WorkspaceSetupGuide />);
+ rerender(<WorkspaceSetupGuide />);
+
+ expect(mocks.captureMetric).toHaveBeenCalledTimes(1);
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide step completed",
+ properties: {
+ journey: "workspace-setup",
+ scenario: "unselected",
+ collaboration_type: "unselected",
+ completed_steps: ["create-project"],
+ completed_step_count: 1,
+ total_step_count: 3,
+ next_step: "connect-instance",
+ step: "create-project",
+ },
+ });
+ });
+
+ test("records journey completion after visible guide becomes complete", () => {
+ mocks.scenarioId = "query-data";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ });
+ const { rerender } = render(<WorkspaceSetupGuide />);
+ mocks.captureMetric.mockClear();
+
+ mocks.guideContext = guideContext({
+ ...mocks.guideContext,
+ hasRunStatement: true,
+ });
+ rerender(<WorkspaceSetupGuide />);
+
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide completed",
+ properties: {
+ journey: "query-data",
+ scenario: "query-data",
+ collaboration_type: "unselected",
+ completed_steps: [
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ ],
+ completed_step_count: 4,
+ total_step_count: 4,
+ },
+ });
});
test("shows generic completion with both next actions", () => {
@@ -696,7 +822,7 @@ describe("WorkspaceSetupGuide", () => {
expect(screen.queryByText("workspace-setup-guide.actions.change")).not.toBeInTheDocument();
});
- test("does not record scenario guide lifecycle analytics", () => {
+ test("records the initial guide progress once", () => {
mocks.scenarioId = "create-database-change";
mocks.guideContext = guideContext({
hasProject: true,
@@ -707,6 +833,38 @@ describe("WorkspaceSetupGuide", () => {
render(<WorkspaceSetupGuide />);
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: "workspace-setup-guide.progress-observed.create-database-change.v1",
+ newState: true,
+ });
+ expect(mocks.captureMetric).toHaveBeenCalledTimes(1);
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup guide progress observed",
+ properties: {
+ journey: "create-database-change",
+ scenario: "create-database-change",
+ collaboration_type: "unselected",
+ completed_steps: [
+ "create-project",
+ "connect-instance",
+ "create-database-change",
+ ],
+ completed_step_count: 3,
+ total_step_count: 4,
+ next_step: "explore-database",
+ observation: "initial",
+ },
+ });
+ });
+
+ test("does not record initial guide progress after it was observed", () => {
+ mocks.scenarioId = "create-database-change";
+ mocks.introState[
+ "workspace-setup-guide.progress-observed.create-database-change.v1"
+ ] = true;
+
+ render(<WorkspaceSetupGuide />);
+
expect(mocks.captureMetric).not.toHaveBeenCalled();
});
});
diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
index 285559ffbc..3b3eaa3e5b 100644
--- a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
@@ -1,6 +1,11 @@
import { CheckCircle, Circle, CircleHelp, ListChecks, X } from "lucide-react";
-import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
+import {
+ type BehaviorMetricName,
+ createBehaviorMetric,
+} from "@/app/analytics/behavior";
+import { behaviorAnalytics } from "@/app/analytics/provider";
import { router, useCurrentRoute } from "@/app/router";
import {
getHowBytebaseWorksGuideContent,
@@ -20,9 +25,11 @@ import { preCreateIssue } from "@/lib/plan/issue";
import { PRODUCT_INTRO_QUERY_KEY } from "@/lib/productIntro";
import { cn } from "@/lib/utils";
import { useAppStore } from "@/stores/app";
+import { getGuideAnalyticsProperties } from "./analytics";
import {
GUIDE_PROGRESS_KEYS,
guideCompletionAcknowledgedKey,
+ guideProgressObservedKey,
} from "./progress";
import { resolveGuide } from "./resolve";
import { getGuideJourney } from "./scenarios";
@@ -31,7 +38,7 @@ import {
readSelectedGuideScenarioId,
} from "./selection";
import { GUIDE_STEP_REGISTRY } from "./steps";
-import type { GuideStepId, ResolvedGuideStep } from "./types";
+import type { GuideAction, GuideStepId, ResolvedGuideStep } from "./types";
import { useGuideContext } from "./useGuideContext";
export function WorkspaceSetupGuide() {
@@ -47,6 +54,8 @@ export function WorkspaceSetupGuide() {
const completionAcknowledged = useIntroStateByKey(
guideCompletionAcknowledgedKey(journey.id)
);
+ const progressObservedKey = guideProgressObservedKey(journey.id);
+ const progressObserved = useIntroStateByKey(progressObservedKey);
const allowMultipleMembers =
workspaceUsage === "team" && !completionAcknowledged;
const guideEnabled = useAppStore((state) =>
@@ -73,17 +82,33 @@ export function WorkspaceSetupGuide() {
const completionWideWidthRef = useRef(0);
const stepViewportRef = useRef<HTMLDivElement>(null);
const stepMeasurementRef = useRef<HTMLDivElement>(null);
+ const analyticsJourneyRef = useRef<string | undefined>(undefined);
+ const completedStepsRef = useRef<readonly GuideStepId[] | undefined>(
+ undefined
+ );
+ const wasIncompleteRef = useRef(false);
+ const observedProgressKeyRef = useRef<string | undefined>(undefined);
const guide = useMemo(
() =>
resolveGuide({
journey,
- registry: GUIDE_STEP_REGISTRY,
+ definitions: GUIDE_STEP_REGISTRY,
context,
selectedStepId,
}),
[context, journey, selectedStepId]
);
const primaryAction = guide.actionStep?.actions.primary;
+ const guideAnalyticsProperties = useMemo(
+ () =>
+ getGuideAnalyticsProperties({
+ guide,
+ journey,
+ scenarioId,
+ workspaceUsage,
+ }),
+ [guide, journey, scenarioId, workspaceUsage]
+ );
const compactStep =
guide.highlightedStep ?? guide.actionStep ?? guide.steps[0];
const compactStepIndex = compactStep
@@ -148,9 +173,83 @@ export function WorkspaceSetupGuide() {
updateOverflow();
return () => observer.disconnect();
}, [completionCompact, guide.complete, i18n.resolvedLanguage, journey.id]);
+
+ const captureGuideMetric = (
+ event: BehaviorMetricName,
+ properties: Record<string, unknown> = {}
+ ) => {
+ behaviorAnalytics.captureMetric(
+ createBehaviorMetric(event, {
+ properties: { ...guideAnalyticsProperties, ...properties },
+ })
+ );
+ };
+ const guideVisible =
+ !dismissed &&
+ guideEnabled &&
+ !loading &&
+ !(guide.complete && completionAcknowledged);
+
+ useEffect(() => {
+ if (
+ !guideVisible ||
+ progressObserved ||
+ observedProgressKeyRef.current === progressObservedKey
+ ) {
+ return;
+ }
+
+ observedProgressKeyRef.current = progressObservedKey;
+ useAppStore.getState().saveIntroStateByKey({
+ key: progressObservedKey,
+ newState: true,
+ });
+ captureGuideMetric("workspace setup guide progress observed", {
+ observation: "initial",
+ });
+ }, [captureGuideMetric, guideVisible, progressObserved, progressObservedKey]);
+
+ useEffect(() => {
+ if (!guideVisible) return;
+
+ const completedSteps = guideAnalyticsProperties.completed_steps;
+ if (analyticsJourneyRef.current !== journey.id) {
+ analyticsJourneyRef.current = journey.id;
+ completedStepsRef.current = completedSteps;
+ wasIncompleteRef.current = !guide.complete;
+ return;
+ }
+
+ const previousCompletedSteps = new Set(completedStepsRef.current);
+ for (const step of completedSteps) {
+ if (!previousCompletedSteps.has(step)) {
+ captureGuideMetric("workspace setup guide step completed", { step });
+ }
+ }
+ if (wasIncompleteRef.current && guide.complete) {
+ captureGuideMetric("workspace setup guide completed");
+ }
+ completedStepsRef.current = completedSteps;
+ wasIncompleteRef.current = !guide.complete;
+ }, [
+ captureGuideMetric,
+ guide.complete,
+ guideAnalyticsProperties,
+ guideVisible,
+ journey.id,
+ ]);
+
+ const captureStepAction = (step: ResolvedGuideStep, action: GuideAction) => {
+ captureGuideMetric("workspace setup guide step action selected", {
+ step: step.definition.id,
+ action_type: action.type,
+ });
+ };
+
const onSelectStep = (step: ResolvedGuideStep) => {
setSelectedStepId(step.definition.id);
const action = step.actions.select;
+ if (action) captureStepAction(step, action);
if (action?.type === "navigate") void router.push(action.target);
if (action?.type === "create-change") {
void preCreateIssue(action.project, [action.database]);
@@ -158,6 +257,7 @@ export function WorkspaceSetupGuide() {
};
const handleDismiss = () => {
+ captureGuideMetric("workspace setup guide dismissed");
useAppStore.getState().saveIntroStateByKey({
key: guide.complete
? guideCompletionAcknowledgedKey(journey.id)
@@ -166,12 +266,7 @@ export function WorkspaceSetupGuide() {
});
};
- if (
- dismissed ||
- !guideEnabled ||
- loading ||
- (guide.complete && completionAcknowledged)
- ) {
+ if (!guideVisible) {
return null;
}
@@ -363,7 +458,7 @@ export function WorkspaceSetupGuide() {
<Button
type="button"
appearance="secondary"
- data-testid={`setup-step-${step.definition.analyticsKey}`}
+ data-testid={`setup-step-${step.definition.id}`}
className={cn(
"inline-flex h-auto items-center justify-start gap-x-1 rounded-sm px-2.5 py-1.5 text-sm font-medium whitespace-nowrap 2xl:gap-x-2 2xl:px-3 2xl:py-2 2xl:text-base",
highlighted
@@ -432,14 +527,22 @@ export function WorkspaceSetupGuide() {
/>
)}
{!guide.complete && primaryAction?.type === "open-sql-editor" && (
- <SQLEditorButton
- data-testid="active-action"
- database={primaryAction.database}
- openInNewTab
- size="sm"
- className="2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"
- label={t("workspace-setup-guide.actions.query")}
- />
+ <span
+ onClickCapture={() => {
+ if (guide.actionStep) {
+ captureStepAction(guide.actionStep, primaryAction);
+ }
+ }}
+ >
+ <SQLEditorButton
+ data-testid="active-action"
+ database={primaryAction.database}
+ openInNewTab
+ size="sm"
+ className="2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"
+ label={t("workspace-setup-guide.actions.query")}
+ />
+ </span>
)}
<Button
type="button"
diff --git a/frontend/src/modules/workspace-setup-guide/analytics.test.ts b/frontend/src/modules/workspace-setup-guide/analytics.test.ts
new file mode 100644
index 0000000000..95d3565906
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/analytics.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, test } from "vitest";
+import { getGuideAnalyticsProperties } from "./analytics";
+import type { GuideJourney, ResolvedGuide } from "./types";
+
+const journey: GuideJourney = {
+ id: "query-data",
+ scenarioId: "query-data",
+ completionTitleKey: "",
+ completionDescriptionKey: "",
+ completionActions: [],
+ steps: [
+ { stepId: "create-project" },
+ { stepId: "connect-instance", dependsOn: ["create-project"] },
+ { stepId: "explore-database", dependsOn: ["connect-instance"] },
+ { stepId: "query-data", dependsOn: ["explore-database"] },
+ ],
+};
+
+const resolvedStep = (
+ index: number,
+ overrides: Partial<ResolvedGuide["steps"][number]> = {}
+): ResolvedGuide["steps"][number] => ({
+ journeyStep: journey.steps[index],
+ definition: {
+ id: journey.steps[index].stepId,
+ } as ResolvedGuide["steps"][number]["definition"],
+ done: false,
+ blocked: false,
+ actions: {},
+ ...overrides,
+});
+
+const guide: ResolvedGuide = {
+ steps: [
+ resolvedStep(0, { done: true }),
+ resolvedStep(1),
+ resolvedStep(2, { blocked: true }),
+ resolvedStep(3, { blocked: true }),
+ ],
+ complete: false,
+ activeStep: resolvedStep(1),
+ highlightedStep: undefined,
+ actionStep: undefined,
+};
+
+describe("guide analytics", () => {
+ test("records a safe progress snapshot for the selected journey", () => {
+ expect(
+ getGuideAnalyticsProperties({
+ guide,
+ journey,
+ scenarioId: "query-data",
+ workspaceUsage: "team",
+ })
+ ).toEqual({
+ journey: "query-data",
+ scenario: "query-data",
+ collaboration_type: "team",
+ completed_steps: ["create-project"],
+ completed_step_count: 1,
+ total_step_count: 4,
+ next_step: "connect-instance",
+ });
+ });
+
+ test("uses explicit unselected values and omits the next step after completion", () => {
+ expect(
+ getGuideAnalyticsProperties({
+ guide: { ...guide, complete: true, activeStep: undefined },
+ journey,
+ })
+ ).toEqual({
+ journey: "query-data",
+ scenario: "unselected",
+ collaboration_type: "unselected",
+ completed_steps: ["create-project"],
+ completed_step_count: 1,
+ total_step_count: 4,
+ });
+ });
+});
diff --git a/frontend/src/modules/workspace-setup-guide/analytics.ts b/frontend/src/modules/workspace-setup-guide/analytics.ts
new file mode 100644
index 0000000000..91a72b01dd
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/analytics.ts
@@ -0,0 +1,34 @@
+import type {
+ GuideJourney,
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+ ResolvedGuide,
+} from "./types";
+
+export const getGuideAnalyticsProperties = ({
+ guide,
+ journey,
+ scenarioId,
+ workspaceUsage,
+}: {
+ guide: ResolvedGuide;
+ journey: GuideJourney;
+ scenarioId?: GuideScenarioId;
+ workspaceUsage?: GuideWorkspaceUsage;
+}) => {
+ const completedSteps = guide.steps
+ .filter((step) => step.done)
+ .map((step) => step.definition.id);
+
+ return {
+ journey: journey.id,
+ scenario: scenarioId ?? "unselected",
+ collaboration_type: workspaceUsage ?? "unselected",
+ completed_steps: completedSteps,
+ completed_step_count: completedSteps.length,
+ total_step_count: guide.steps.length,
+ ...(guide.complete || !guide.activeStep
+ ? {}
+ : { next_step: guide.activeStep.definition.id }),
+ };
+};
diff --git a/frontend/src/modules/workspace-setup-guide/progress.ts b/frontend/src/modules/workspace-setup-guide/progress.ts
index 8f29e3624f..5cbea04d8e 100644
--- a/frontend/src/modules/workspace-setup-guide/progress.ts
+++ b/frontend/src/modules/workspace-setup-guide/progress.ts
@@ -10,3 +10,6 @@ export const GUIDE_PROGRESS_KEYS = {
export const guideCompletionAcknowledgedKey = (id: GuideJourneyId) =>
`workspace-setup-guide.completed.${id}`;
+
+export const guideProgressObservedKey = (id: GuideJourneyId) =>
+ `workspace-setup-guide.progress-observed.${id}.v1`;
diff --git a/frontend/src/modules/workspace-setup-guide/resolve.test.ts b/frontend/src/modules/workspace-setup-guide/resolve.test.ts
index 7ddee3add3..7693ca7ed3 100644
--- a/frontend/src/modules/workspace-setup-guide/resolve.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/resolve.test.ts
@@ -10,7 +10,6 @@ import type {
GuideJourney,
GuideStepDefinition,
GuideStepId,
- GuideStepRegistry,
} from "./types";
const STEP_IDS: GuideStepId[] = [
@@ -52,7 +51,6 @@ const completionById: Record<GuideStepId, keyof GuideContext> = {
const definition = (id: GuideStepId): GuideStepDefinition => ({
id,
- analyticsKey: id === "add-member" ? "add-teammate" : id,
labelKey: `label.${id}`,
descriptionKey: `description.${id}`,
isComplete: (context) => Boolean(context[completionById[id]]),
@@ -60,9 +58,7 @@ const definition = (id: GuideStepId): GuideStepDefinition => ({
resolveActions: () => ({}),
});
-const registry = Object.fromEntries(
- STEP_IDS.map((id) => [id, definition(id)])
-) as GuideStepRegistry;
+const definitions = STEP_IDS.map(definition);
const generic: GuideJourney = {
id: "workspace-setup",
@@ -100,8 +96,8 @@ const queryData: GuideJourney = {
describe("validateGuideJourney", () => {
test("accepts selected and generic graphs", () => {
- expect(() => validateGuideJourney(generic, registry)).not.toThrow();
- expect(() => validateGuideJourney(queryData, registry)).not.toThrow();
+ expect(() => validateGuideJourney(generic, definitions)).not.toThrow();
+ expect(() => validateGuideJourney(queryData, definitions)).not.toThrow();
});
test.each([
@@ -137,14 +133,23 @@ describe("validateGuideJourney", () => {
],
])("rejects an %s graph", (_name, journey, message) => {
expect(() =>
- validateGuideJourney(journey as GuideJourney, registry)
+ validateGuideJourney(journey as GuideJourney, definitions)
).toThrow(message);
});
test("rejects duplicate journey ids", () => {
- expect(() => validateGuideJourneys([generic, generic], registry)).toThrow(
- "duplicate journey"
- );
+ expect(() =>
+ validateGuideJourneys([generic, generic], definitions)
+ ).toThrow("duplicate journey");
+ });
+
+ test("rejects duplicate step definitions", () => {
+ expect(() =>
+ validateGuideJourneys(
+ [generic],
+ [...definitions, definition("create-project")]
+ )
+ ).toThrow("duplicate step definition");
});
});
@@ -152,7 +157,7 @@ describe("resolveGuide", () => {
test("uses generic setup order and dependencies", () => {
const guide = resolveGuide({
journey: generic,
- registry,
+ definitions,
context: createContext(),
});
expect(guide.steps.map((step) => step.definition.id)).toEqual([
@@ -166,7 +171,7 @@ describe("resolveGuide", () => {
test("keeps satisfied prerequisites visible", () => {
const guide = resolveGuide({
journey: queryData,
- registry,
+ definitions,
context: createContext({
hasProject: true,
hasInstance: true,
@@ -186,7 +191,7 @@ describe("resolveGuide", () => {
test("shows the full chain and blocks on missing prerequisites", () => {
const guide = resolveGuide({
journey: queryData,
- registry,
+ definitions,
context: createContext(),
});
expect(guide.steps.map((step) => step.definition.id)).toEqual([
@@ -202,7 +207,7 @@ describe("resolveGuide", () => {
test("allows a completed visible prerequisite to stay selected", () => {
const guide = resolveGuide({
journey: queryData,
- registry,
+ definitions,
context: createContext({ hasProject: true }),
selectedStepId: "create-project",
});
@@ -213,7 +218,7 @@ describe("resolveGuide", () => {
test("returns completion without an active action", () => {
const guide = resolveGuide({
journey: queryData,
- registry,
+ definitions,
context: createContext({
hasProject: true,
hasInstance: true,
diff --git a/frontend/src/modules/workspace-setup-guide/resolve.ts b/frontend/src/modules/workspace-setup-guide/resolve.ts
index 18c51e157a..aa69fd1787 100644
--- a/frontend/src/modules/workspace-setup-guide/resolve.ts
+++ b/frontend/src/modules/workspace-setup-guide/resolve.ts
@@ -1,14 +1,27 @@
import type {
GuideContext,
GuideJourney,
+ GuideStepDefinition,
GuideStepId,
- GuideStepRegistry,
ResolvedGuide,
} from "./types";
-export const validateGuideJourney = (
+const definitionsById = (definitions: readonly GuideStepDefinition[]) => {
+ const byId = new Map<GuideStepId, GuideStepDefinition>();
+ for (const definition of definitions) {
+ if (byId.has(definition.id)) {
+ throw new Error(
+ `Guide contains duplicate step definition ${definition.id}`
+ );
+ }
+ byId.set(definition.id, definition);
+ }
+ return byId;
+};
+
+const validateGuideJourneyWithDefinitions = (
journey: GuideJourney,
- registry: GuideStepRegistry
+ definitions: ReadonlyMap<GuideStepId, GuideStepDefinition>
) => {
if (journey.steps.length === 0) {
throw new Error(
@@ -18,7 +31,7 @@ export const validateGuideJourney = (
const indexById = new Map<GuideStepId, number>();
for (const [index, step] of journey.steps.entries()) {
- if (!registry[step.stepId]) {
+ if (!definitions.has(step.stepId)) {
throw new Error(
`Guide journey ${journey.id} references unregistered step ${step.stepId}`
);
@@ -74,10 +87,18 @@ export const validateGuideJourney = (
}
};
+export const validateGuideJourney = (
+ journey: GuideJourney,
+ definitions: readonly GuideStepDefinition[]
+) => {
+ validateGuideJourneyWithDefinitions(journey, definitionsById(definitions));
+};
+
export const validateGuideJourneys = (
journeys: readonly GuideJourney[],
- registry: GuideStepRegistry
+ definitions: readonly GuideStepDefinition[]
) => {
+ const definitionById = definitionsById(definitions);
const ids = new Set<string>();
for (const journey of journeys) {
if (ids.has(journey.id)) {
@@ -86,29 +107,35 @@ export const validateGuideJourneys = (
);
}
ids.add(journey.id);
- validateGuideJourney(journey, registry);
+ validateGuideJourneyWithDefinitions(journey, definitionById);
}
};
export const resolveGuide = ({
journey,
- registry,
+ definitions,
context,
selectedStepId,
}: {
journey: GuideJourney;
- registry: GuideStepRegistry;
+ definitions: readonly GuideStepDefinition[];
context: GuideContext;
selectedStepId?: GuideStepId;
}): ResolvedGuide => {
+ const definitionById = definitionsById(definitions);
const doneById = new Map(
journey.steps.map(({ stepId }) => [
stepId,
- registry[stepId].isComplete(context),
+ definitionById.get(stepId)?.isComplete(context) ?? false,
])
);
const allSteps = journey.steps.map((journeyStep) => {
- const definition = registry[journeyStep.stepId];
+ const definition = definitionById.get(journeyStep.stepId);
+ if (!definition) {
+ throw new Error(
+ `Guide journey ${journey.id} references unregistered step ${journeyStep.stepId}`
+ );
+ }
const done = doneById.get(journeyStep.stepId) ?? false;
return {
journeyStep,
diff --git a/frontend/src/modules/workspace-setup-guide/selection.test.ts b/frontend/src/modules/workspace-setup-guide/selection.test.ts
index e9ef53891f..ee034e84b2 100644
--- a/frontend/src/modules/workspace-setup-guide/selection.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/selection.test.ts
@@ -77,6 +77,7 @@ describe("workspace setup guide scenario selection", () => {
expect(isGuideScenarioId("create-database-change")).toBe(true);
expect(isGuideScenarioId("learn-bytebase-basics")).toBe(false);
expect(isGuideScenarioId("protect-sensitive-data")).toBe(false);
+ expect(isGuideScenarioId("toString")).toBe(false);
expect(isGuideScenarioId(undefined)).toBe(false);
});
diff --git a/frontend/src/modules/workspace-setup-guide/selection.ts b/frontend/src/modules/workspace-setup-guide/selection.ts
index 8f066b2e8b..1bc02fe6e3 100644
--- a/frontend/src/modules/workspace-setup-guide/selection.ts
+++ b/frontend/src/modules/workspace-setup-guide/selection.ts
@@ -9,10 +9,12 @@ import {
storageKeyWorkspaceSetupGuideScenario,
storageKeyWorkspaceSetupGuideWorkspaceUsage,
} from "@/utils/storage-keys";
+import { GUIDE_SCENARIO_REGISTRY } from "./scenarios";
import type { GuideScenarioId, GuideWorkspaceUsage } from "./types";
export const isGuideScenarioId = (value: unknown): value is GuideScenarioId =>
- value === "query-data" || value === "create-database-change";
+ typeof value === "string" &&
+ Object.prototype.hasOwnProperty.call(GUIDE_SCENARIO_REGISTRY, value);
export const isGuideWorkspaceUsage = (
value: unknown
diff --git a/frontend/src/modules/workspace-setup-guide/steps.test.ts b/frontend/src/modules/workspace-setup-guide/steps.test.ts
index effbfc86f4..351e1190f0 100644
--- a/frontend/src/modules/workspace-setup-guide/steps.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/steps.test.ts
@@ -19,6 +19,12 @@ import {
import { GUIDE_STEP_REGISTRY } from "./steps";
import type { GuideContext, GuideStepId } from "./types";
+const getStepDefinition = (id: GuideStepId) => {
+ const definition = GUIDE_STEP_REGISTRY.find((step) => step.id === id);
+ if (!definition) throw new Error(`Missing step definition: ${id}`);
+ return definition;
+};
+
const createContext = (
overrides: Partial<GuideContext> = {}
): GuideContext => ({
@@ -40,7 +46,7 @@ const createContext = (
describe("GUIDE_STEP_REGISTRY", () => {
test("contains only reusable resource and customer-action definitions", () => {
- expect(Object.keys(GUIDE_STEP_REGISTRY)).toEqual([
+ expect(GUIDE_STEP_REGISTRY.map(({ id }) => id)).toEqual([
"create-project",
"connect-instance",
"explore-database",
@@ -65,14 +71,14 @@ describe("GUIDE_STEP_REGISTRY", () => {
["create-database-change", { hasCreatedChangeIssue: true }],
["add-member", { hasOtherWorkspaceMember: true }],
] as const)("uses observable evidence for %s", (stepId, completed) => {
- expect(
- GUIDE_STEP_REGISTRY[stepId].isComplete(createContext(completed))
- ).toBe(true);
+ expect(getStepDefinition(stepId).isComplete(createContext(completed))).toBe(
+ true
+ );
});
test("keeps database exploration incomplete without a concrete target", () => {
expect(
- GUIDE_STEP_REGISTRY["explore-database"].isComplete(
+ getStepDefinition("explore-database").isComplete(
createContext({ hasExploredDatabase: true })
)
).toBe(false);
@@ -82,7 +88,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
"always opens the workspace project list with the create highlight",
(context) => {
expect(
- GUIDE_STEP_REGISTRY["create-project"].resolveActions(context)
+ getStepDefinition("create-project").resolveActions(context)
).toEqual({
select: {
type: "navigate",
@@ -107,7 +113,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
"always opens the project instance list with the create highlight",
(context) => {
expect(
- GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(context)
+ getStepDefinition("connect-instance").resolveActions(context)
).toEqual({
select: {
type: "navigate",
@@ -125,7 +131,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
test("keeps the connect action fixed while its project dependency is blocked", () => {
expect(
- GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(createContext())
+ getStepDefinition("connect-instance").resolveActions(createContext())
).toEqual({
select: {
type: "navigate",
@@ -149,7 +155,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
}),
])("always opens the project database page with its highlight", (context) => {
expect(
- GUIDE_STEP_REGISTRY["explore-database"].resolveActions(context)
+ getStepDefinition("explore-database").resolveActions(context)
).toEqual({
select: {
type: "navigate",
@@ -168,7 +174,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
"always queries the discovered database when completion is %s",
(hasRunStatement) => {
expect(
- GUIDE_STEP_REGISTRY["query-data"].resolveActions(
+ getStepDefinition("query-data").resolveActions(
createContext({
hasRunStatement,
databaseName: "instances/sample/databases/employee",
@@ -191,7 +197,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
"always starts a database change when completion is %s",
(hasCreatedChangeIssue) => {
expect(
- GUIDE_STEP_REGISTRY["create-database-change"].resolveActions(
+ getStepDefinition("create-database-change").resolveActions(
createContext({
hasCreatedChangeIssue,
databaseName: "instances/sample/databases/employee",
@@ -211,7 +217,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
test("opens Users when self-host has no other human user", () => {
const context = createContext();
- expect(GUIDE_STEP_REGISTRY["add-member"].resolveActions(context)).toEqual({
+ expect(getStepDefinition("add-member").resolveActions(context)).toEqual({
select: {
type: "navigate",
target: {
@@ -228,7 +234,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
createContext({ isSaaS: true }),
createContext({ hasOtherHumanUser: true }),
])("opens Members when the teammate can be granted access", (context) => {
- expect(GUIDE_STEP_REGISTRY["add-member"].resolveActions(context)).toEqual({
+ expect(getStepDefinition("add-member").resolveActions(context)).toEqual({
select: {
type: "navigate",
target: {
@@ -251,7 +257,7 @@ describe("GUIDE_STEP_REGISTRY", () => {
["add-member", WORKSPACE_ROUTE_MEMBERS, true],
] as const)("matches %s on %s", (stepId, name, expected) => {
expect(
- GUIDE_STEP_REGISTRY[stepId as GuideStepId].matchesRoute({
+ getStepDefinition(stepId as GuideStepId).matchesRoute({
name,
params: {},
})
diff --git a/frontend/src/modules/workspace-setup-guide/steps.ts b/frontend/src/modules/workspace-setup-guide/steps.ts
index 5bd1f2856d..50e48d2f09 100644
--- a/frontend/src/modules/workspace-setup-guide/steps.ts
+++ b/frontend/src/modules/workspace-setup-guide/steps.ts
@@ -19,7 +19,7 @@ import { extractProjectResourceName } from "@/utils/v1/project";
import type {
GuideContext,
GuideStepActions,
- GuideStepRegistry,
+ GuideStepDefinition,
} from "./types";
const isRouteInside = (name: string | undefined, parent: string) =>
@@ -57,10 +57,9 @@ const databaseActions = (context: GuideContext): GuideStepActions => ({
},
});
-export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
- "create-project": {
+export const GUIDE_STEP_REGISTRY: readonly GuideStepDefinition[] = [
+ {
id: "create-project",
- analyticsKey: "create-project",
labelKey: "workspace-setup-guide.steps.project",
descriptionKey: "workspace-setup-guide.descriptions.project",
isComplete: (context) => context.hasProject,
@@ -77,9 +76,8 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
},
}),
},
- "connect-instance": {
+ {
id: "connect-instance",
- analyticsKey: "connect-instance",
labelKey: "workspace-setup-guide.steps.instance",
descriptionKey: "workspace-setup-guide.descriptions.instance",
isComplete: (context) => context.hasInstance,
@@ -87,9 +85,8 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
isRouteInside(route.name, PROJECT_V1_ROUTE_INSTANCES),
resolveActions: connectInstanceActions,
},
- "explore-database": {
+ {
id: "explore-database",
- analyticsKey: "explore-database",
labelKey: "workspace-setup-guide.steps.database",
descriptionKey: "workspace-setup-guide.descriptions.database",
isComplete: (context) =>
@@ -100,9 +97,8 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
isRouteInside(route.name, PROJECT_V1_ROUTE_DATABASES),
resolveActions: databaseActions,
},
- "query-data": {
+ {
id: "query-data",
- analyticsKey: "query-data",
labelKey: "workspace-setup-guide.steps.query-data",
descriptionKey: "workspace-setup-guide.descriptions.query-data",
isComplete: (context) => context.hasRunStatement,
@@ -118,9 +114,8 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
},
}),
},
- "create-database-change": {
+ {
id: "create-database-change",
- analyticsKey: "create-database-change",
labelKey: "workspace-setup-guide.steps.create-database-change",
descriptionKey: "workspace-setup-guide.descriptions.create-database-change",
isComplete: (context) => context.hasCreatedChangeIssue,
@@ -134,9 +129,8 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
},
}),
},
- "add-member": {
+ {
id: "add-member",
- analyticsKey: "add-teammate",
labelKey: "workspace-setup-guide.steps.add-teammate",
descriptionKey: "workspace-setup-guide.descriptions.add-teammate",
isComplete: (context) => context.hasOtherWorkspaceMember,
@@ -165,4 +159,4 @@ export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
};
},
},
-};
+];
diff --git a/frontend/src/modules/workspace-setup-guide/types.ts b/frontend/src/modules/workspace-setup-guide/types.ts
index bf177799ae..44c9c69230 100644
--- a/frontend/src/modules/workspace-setup-guide/types.ts
+++ b/frontend/src/modules/workspace-setup-guide/types.ts
@@ -14,10 +14,6 @@ export type GuideWorkspaceUsage = "team" | "solo";
export type GuideJourneyId = "workspace-setup" | GuideScenarioId;
-export type GuideAnalyticsKey =
- | Exclude<GuideStepId, "add-member">
- | "add-teammate";
-
export type GuideRoute = Pick<ReactRoute, "name" | "params">;
export type GuideContext = {
@@ -58,7 +54,6 @@ export type GuideStepActions = {
export type GuideStepDefinition = {
id: GuideStepId;
- analyticsKey: GuideAnalyticsKey;
labelKey: string;
descriptionKey: string;
isComplete: (context: GuideContext) => boolean;
@@ -66,10 +61,6 @@ export type GuideStepDefinition = {
resolveActions: (context: GuideContext) => GuideStepActions;
};
-export type GuideStepRegistry = Readonly<
- Record<GuideStepId, GuideStepDefinition>
->;
-
export type GuideJourneyStep = {
stepId: GuideStepId;
kind?: "prerequisite" | "learning" | "modifier";
diff --git a/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx b/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
index 7e456d8c3d..dd0d451b6b 100644
--- a/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
+++ b/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
@@ -42,6 +42,8 @@ const mocks = vi.hoisted(() => ({
setRecentProject: vi.fn(),
routerReplace: vi.fn(),
captureMetric: vi.fn(),
+ introState: {} as Record<string, boolean>,
+ saveIntroStateByKey: vi.fn(),
clearGuideWorkspaceUsage: vi.fn(),
clearSelectedGuideScenarioId: vi.fn(),
saveGuideWorkspaceUsage: vi.fn(),
@@ -82,10 +84,12 @@ vi.mock("@/hooks/useAppState", () => ({
createProject: mocks.createProject,
setRecentProject: mocks.setRecentProject,
}),
+ useIntroStateByKey: (key: string) => mocks.introState[key] ?? false,
}));
-vi.mock("@/stores/app", () => ({
- useAppStore: (
+vi.mock("@/stores/app", () => {
+ const useAppStore = Object.assign(
+ (
selector: (state: {
workspacePolicy: IamPolicy;
updateUser: typeof mocks.updateUser;
@@ -97,7 +101,7 @@ vi.mock("@/stores/app", () => ({
isSaaSMode: () => boolean;
}) => unknown
) =>
- selector({
+ selector({
workspacePolicy: mocks.workspacePolicy,
updateUser: mocks.updateUser,
updateWorkspace: mocks.updateWorkspace,
@@ -108,9 +112,16 @@ vi.mock("@/stores/app", () => ({
instances: mocks.sampleInstances,
},
},
- isSaaSMode: () => mocks.isSaaSMode,
- }),
-}));
+ isSaaSMode: () => mocks.isSaaSMode,
+ }),
+ {
+ getState: () => ({
+ saveIntroStateByKey: mocks.saveIntroStateByKey,
+ }),
+ }
+ );
+ return { useAppStore };
+});
vi.mock("@/app/router", async (importOriginal) => ({
...(await importOriginal<typeof import("@/app/router")>()),
@@ -253,6 +264,10 @@ beforeEach(async () => {
mocks.sampleAvailable = true;
mocks.sampleInstances = [];
mocks.isSaaSMode = false;
+ mocks.introState = {};
+ mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {
+ mocks.introState[key] = newState;
+ });
mocks.workspacePolicy = {
bindings: [
{
@@ -272,6 +287,29 @@ beforeEach(async () => {
});
describe("WorkspaceSetupPage", () => {
+ test("records setup page entry only once per lifecycle", () => {
+ const first = renderIntoContainer(<WorkspaceSetupPage />);
+ first.render();
+
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup page entered",
+ properties: { setup_version: "v1" },
+ });
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: "workspace-setup.page-entered.v1",
+ newState: true,
+ });
+
+ first.render();
+ first.unmount();
+
+ const second = renderIntoContainer(<WorkspaceSetupPage />);
+ second.render();
+
+ expect(mocks.captureMetric).toHaveBeenCalledTimes(1);
+ second.unmount();
+ });
+
test("uses the shared step indicator for both setup steps", async () => {
const page = renderIntoContainer(<WorkspaceSetupPage />);
page.render();
@@ -378,7 +416,10 @@ describe("WorkspaceSetupPage", () => {
expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
"create-database-change"
);
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup page entered",
+ properties: { setup_version: "v1" },
+ });
page.unmount();
});
@@ -408,7 +449,10 @@ describe("WorkspaceSetupPage", () => {
"query-data"
);
expect(mocks.saveGuideWorkspaceUsage).toHaveBeenCalledWith("team");
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup page entered",
+ properties: { setup_version: "v1" },
+ });
const submit = [...page.container.querySelectorAll("button")].find(
(button) => button.textContent?.includes("Setup my workspace")
@@ -511,7 +555,7 @@ describe("WorkspaceSetupPage", () => {
expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
"create-database-change"
);
- expect(mocks.captureMetric).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalled();
page.unmount();
});
@@ -581,7 +625,7 @@ describe("WorkspaceSetupPage", () => {
expect(mocks.clearGuideWorkspaceUsage).toHaveBeenCalledOnce();
expect(mocks.saveSelectedGuideScenarioId).not.toHaveBeenCalled();
expect(mocks.saveGuideWorkspaceUsage).not.toHaveBeenCalled();
- expect(mocks.captureMetric).toHaveBeenCalledTimes(2);
+ expect(mocks.captureMetric).toHaveBeenCalledTimes(3);
expect(mocks.captureMetric).toHaveBeenCalledWith({
event: "workspace setup submitted",
properties: {
diff --git a/frontend/src/routes/auth/WorkspaceSetupPage.tsx b/frontend/src/routes/auth/WorkspaceSetupPage.tsx
index aa9f786854..59013064fd 100644
--- a/frontend/src/routes/auth/WorkspaceSetupPage.tsx
+++ b/frontend/src/routes/auth/WorkspaceSetupPage.tsx
@@ -18,6 +18,7 @@ import { StepIndicator } from "@/components/ui/step-indicator";
import {
useCreateProject,
useCurrentUser,
+ useIntroStateByKey,
useWorkspace,
useWorkspacePermission,
} from "@/hooks/useAppState";
@@ -51,6 +52,9 @@ import {
import { extractGrpcErrorMessage } from "@/utils/connect";
import { WorkspaceSetupQuestionnaireStep } from "./WorkspaceSetupQuestionnaireStep";
+const WORKSPACE_SETUP_PAGE_ENTERED_KEY = "workspace-setup.page-entered.v1";
+const WORKSPACE_SETUP_VERSION = "v1";
+
export function WorkspaceSetupPage() {
const { t } = useTranslation();
const currentUser = useCurrentUser();
@@ -71,6 +75,8 @@ export function WorkspaceSetupPage() {
const workspacePolicy = useAppStore((state) => state.workspacePolicy);
const canUpdateWorkspace = useWorkspacePermission("bb.workspaces.update");
const canCreateProject = useWorkspacePermission("bb.projects.create");
+ const setupPageEntered = useIntroStateByKey(WORKSPACE_SETUP_PAGE_ENTERED_KEY);
+ const setupPageEnteredRef = useRef(false);
// Show workspace name field only if the user is the sole member of the
// workspace (i.e. they just created it), not when they were invited.
@@ -115,6 +121,27 @@ export function WorkspaceSetupPage() {
shouldCreateProject && enableSampleDatabases && canPrepareSample;
const canEnableSample = !!projectTitle.trim() && !!projectResourceId;
+ useEffect(() => {
+ if (
+ !currentUser.name ||
+ !workspace?.name ||
+ setupPageEntered ||
+ setupPageEnteredRef.current
+ ) {
+ return;
+ }
+ setupPageEnteredRef.current = true;
+ useAppStore.getState().saveIntroStateByKey({
+ key: WORKSPACE_SETUP_PAGE_ENTERED_KEY,
+ newState: true,
+ });
+ behaviorAnalytics.captureMetric(
+ createBehaviorMetric("workspace setup page entered", {
+ properties: { setup_version: WORKSPACE_SETUP_VERSION },
+ })
+ );
+ }, [currentUser.name, setupPageEntered, workspace?.name]);
+
const validateProjectResourceId = useCallback(
async (id: string): Promise<ValidatedMessage[]> => {
try {