feat(onboarding): funnel analytics for the new flow

frontend/common/constants.ts

@@ -260,6 +260,18 @@ const Constants = {
       'category': 'User',
       'event': `User oauth ${type}`,
     }),
+    'ONBOARDING_AI_CONNECT': {
+      'category': 'Onboarding',
+      'event': 'Onboarding AI connect used',
+    },
+    'ONBOARDING_FLAG_TOGGLED': {
+      'category': 'Onboarding',
+      'event': 'Onboarding flag toggled',
+    },
+    'ONBOARDING_SNIPPET_COPIED': {
+      'category': 'Onboarding',
+      'event': 'Onboarding snippet copied',
+    },
     'REFERRER_CONVERSION': (referrer: string) => ({
       'category': 'Referrer',
       'event': `${referrer} converted`,

frontend/common/utils/getOnboardingVariant.ts

@@ -0,0 +1,13 @@
+import Utils from './utils'
+
+export type OnboardingVariant = 'control' | 'single_page'
+
+// The served variant name picks the arm ('control' is the reserved key the
+// API reports for the default arm). Enabled with no variant is the
+// pre-conversion boolean flag, which means the new flow.
+export const isSinglePageOnboarding = (): boolean =>
+  Utils.getFlagsmithHasFeature('onboarding_quickstart_flow') &&
+  Utils.getFlagsmithVariant('onboarding_quickstart_flow') !== 'control'
+
+export const getOnboardingVariant = (): OnboardingVariant =>
+  isSinglePageOnboarding() ? 'single_page' : 'control'

frontend/common/utils/utils.tsx

@@ -382,6 +382,9 @@ const Utils = Object.assign({}, BaseUtils, {
   getFlagsmithValue(key: string) {
     return flagsmith.getValue(key)
   },
+  getFlagsmithVariant(key: string) {
+    return flagsmith.getAllFlags()[key]?.variant
+  },
 
   getIdentitiesEndpoint(_project: ProjectType) {
     const project = _project || ProjectStore.model

frontend/web/components/pages/onboarding/GettingStartedGate.tsx

@@ -1,19 +1,20 @@
-import React, { FC } from 'react'
-import Utils from 'common/utils/utils'
+import React, { FC, useEffect } from 'react'
+import {
+  getOnboardingVariant,
+  isSinglePageOnboarding,
+} from 'common/utils/getOnboardingVariant'
+import API from 'project/api'
 import GettingStartedPage from 'components/pages/GettingStartedPage'
 import OnboardingFlow from './OnboardingFlow'
 
-// Gates /getting-started: renders the new onboarding flow when the
-// `onboarding_quickstart_flow` flag is on, otherwise the existing page.
-//
-// Deliberately a flat file, not a folder + barrel - a one-line route gate with
-// no styles or sub-parts, the documented exception to the component-folder
-// convention (frontend/CLAUDE.md rule 8).
-const GettingStartedGate: FC = () =>
-  Utils.getFlagsmithHasFeature('onboarding_quickstart_flow') ? (
-    <OnboardingFlow />
-  ) : (
-    <GettingStartedPage />
-  )
+const GettingStartedGate: FC = () => {
+  const variant = getOnboardingVariant()
+
+  useEffect(() => {
+    API.trackTraits({ onboarding_variant: variant })
+  }, [variant])
+
+  return isSinglePageOnboarding() ? <OnboardingFlow /> : <GettingStartedPage />
+}
 
 export default GettingStartedGate

frontend/web/components/pages/onboarding/OnboardingConnectPanel/ConnectWithAiPanel.tsx

@@ -7,6 +7,7 @@ import { useCopyFeedback } from 'components/pages/onboarding/hooks/useCopyFeedba
 export type ConnectWithAiPanelProps = {
   environmentKey: string
   featureName: string
+  onCopyPrompt?: () => void
 }
 
 // "Connect with AI" tab: an agent-agnostic prompt the user pastes into their
@@ -18,6 +19,7 @@ export type ConnectWithAiPanelProps = {
 const ConnectWithAiPanel: FC<ConnectWithAiPanelProps> = ({
   environmentKey,
   featureName,
+  onCopyPrompt,
 }) => {
   const { copied, copy } = useCopyFeedback()
 
@@ -39,7 +41,14 @@ Detect my stack, install the SDK, and wire ${featureName} into one place. Then r
         <code className='onboarding-connect__prompt-text flex-fill'>
           {aiPrompt}
         </code>
-        <Button theme='outline' size='small' onClick={() => copy(aiPrompt)}>
+        <Button
+          theme='outline'
+          size='small'
+          onClick={() => {
+            copy(aiPrompt)
+            onCopyPrompt?.()
+          }}
+        >
           <span
             className='d-inline-flex align-items-center gap-1'
             aria-live='polite'

frontend/web/components/pages/onboarding/OnboardingConnectPanel/OnboardingConnectPanel.tsx

@@ -30,6 +30,7 @@ export type OnboardingConnectPanelProps = {
   featureName: string
   onCopyInstall?: () => void
   onCopyWire?: () => void
+  onCopyPrompt?: () => void
 }
 
 // Two ways to connect an app to the pre-created flag: paste an agent-agnostic
@@ -40,6 +41,7 @@ const OnboardingConnectPanel: FC<OnboardingConnectPanelProps> = ({
   environmentKey,
   featureName,
   onCopyInstall,
+  onCopyPrompt,
   onCopyWire,
 }) => {
   const [tab, setTab] = useState<ConnectTab>('manual')
@@ -61,6 +63,7 @@ const OnboardingConnectPanel: FC<OnboardingConnectPanelProps> = ({
         <ConnectWithAiPanel
           environmentKey={environmentKey}
           featureName={featureName}
+          onCopyPrompt={onCopyPrompt}
         />
       </OnboardingTabPanel>
 

frontend/web/components/pages/onboarding/OnboardingFlow/OnboardingFlow.tsx

@@ -16,8 +16,12 @@ import { useOnboardingFlag } from 'components/pages/onboarding/hooks/useOnboardi
 import { useOnboardingConnection } from 'components/pages/onboarding/hooks/useOnboardingConnection'
 import { useUpdateOrganisationMutation } from 'common/services/useOrganisation'
 import { useUpdateProjectMutation } from 'common/services/useProject'
+import API from 'project/api'
+import Constants from 'common/constants'
 import './OnboardingFlow.scss'
 
+type OnboardingSnippet = 'install' | 'wire'
+
 // The single-page onboarding flow, rendered at /getting-started when
 // onboarding_quickstart_flow is on (see GettingStartedGate).
 const OnboardingFlow: FC = () => {
@@ -139,6 +143,38 @@ const OnboardingFlow: FC = () => {
     history.push(`${base}/features?feature=${flagId}&tab=${tab}`)
   }
 
+  const diagnosticIds = {
+    environment_id: environment?.id,
+    organisation_id: organisationId,
+    project_id: projectId,
+  }
+  const trackSnippetCopied = (snippet: OnboardingSnippet) =>
+    API.trackEvent({
+      ...Constants.events.ONBOARDING_SNIPPET_COPIED,
+      extra: { ...diagnosticIds, snippet },
+    })
+  const handleCopyInstall = () => {
+    trackSnippetCopied('install')
+    setInstallCopied(true)
+  }
+  const handleCopyWire = () => {
+    trackSnippetCopied('wire')
+    setSnippetCopied(true)
+  }
+  const handleCopyPrompt = () =>
+    API.trackEvent({
+      ...Constants.events.ONBOARDING_AI_CONNECT,
+      extra: diagnosticIds,
+    })
+  const handleToggleFlag = async (enabled: boolean) => {
+    if (await toggleFlag(enabled)) {
+      API.trackEvent({
+        ...Constants.events.ONBOARDING_FLAG_TOGGLED,
+        extra: { ...diagnosticIds, enabled },
+      })
+    }
+  }
+
   if (status === 'creating') {
     return (
       <div className='onboarding-flow mx-auto text-center'>
@@ -177,8 +213,9 @@ const OnboardingFlow: FC = () => {
       <OnboardingConnectPanel
         environmentKey={environmentKey}
         featureName={featureName}
-        onCopyInstall={() => setInstallCopied(true)}
-        onCopyWire={() => setSnippetCopied(true)}
+        onCopyInstall={handleCopyInstall}
+        onCopyWire={handleCopyWire}
+        onCopyPrompt={handleCopyPrompt}
       />
       <OnboardingTerminal
         featureName={featureName}
@@ -196,7 +233,7 @@ const OnboardingFlow: FC = () => {
             tags: flagTags,
           },
         ]}
-        onToggle={(_flag, next) => toggleFlag(next)}
+        onToggle={(_flag, next) => handleToggleFlag(next)}
         togglingFlag={isToggling ? featureName : null}
         togglesReady={flagStateReady}
       />

frontend/web/components/pages/onboarding/hooks/bootstrapOnboarding.ts

@@ -18,17 +18,16 @@ import {
 } from 'common/types/responses'
 import { SmartDefaults } from './useSmartDefaults'
 import { createOrganisationViaAccountStore } from './createOrganisationViaAccountStore'
+import API from 'project/api'
+import Constants from 'common/constants'
 
 type Store = ReturnType<typeof getStore>
 
 const FLAG_NAME = 'show_demo_button'
 const DEFAULT_ORG_NAME = 'My organisation'
 const DEFAULT_PROJECT_NAME = 'My first project'
-// Written on create and matched by name on reuse, so the two must stay in step.
 const DEV_ENVIRONMENT_NAME = 'Development'
 const PROD_ENVIRONMENT_NAME = 'Production'
-// Attached to the demo flag so the flags table shows an "Onboarding" badge.
-// Green from the product tag palette (Constants.tagColors), not an arbitrary hex.
 const ONBOARDING_TAG = {
   color: '#3cb371',
   description: 'Created during onboarding',
@@ -50,13 +49,12 @@ export type OnboardingBootstrap = {
   featureName: string
 }
 
-// Reuse the loaded org, or create one only when the user has none (the plan
-// org cap rejects extra creates with a 403). Create goes through the legacy
-// AccountStore so the shell's current-org selection is populated.
 async function ensureOrganisation(
   store: Store,
   { defaults, existingOrg }: BootstrapInput,
 ): Promise<ExistingOrg> {
+  // Create only when the user has none: the plan org cap rejects extra creates
+  // with a 403. Goes through AccountStore so the shell adopts the new org.
   if (existingOrg) {
     return existingOrg
   }
@@ -71,8 +69,6 @@ async function ensureOrganisation(
   return { id, name }
 }
 
-// Reuse the first project, else create one with Development + Production
-// environments. Avoids stacking up duplicate projects on revisits.
 async function ensureProject(
   store: Store,
   organisationId: number,
@@ -93,6 +89,7 @@ async function ensureProject(
       }),
     )
     .unwrap()
+  API.trackEvent(Constants.events.CREATE_FIRST_PROJECT)
   await store
     .dispatch(
       environmentService.endpoints.createEnvironment.initiate({
@@ -112,8 +109,6 @@ async function ensureProject(
   return project
 }
 
-// Surface an environment key: reuse one (preferring Development), or create it
-// only if the reused project somehow has none.
 async function ensureEnvironments(
   store: Store,
   project: ProjectSummary,
@@ -138,7 +133,6 @@ async function ensureEnvironments(
     .unwrap()
 }
 
-// Find the project's Onboarding tag, if it's been created yet.
 async function findOnboardingTag(
   store: Store,
   projectId: number,
@@ -149,8 +143,6 @@ async function findOnboardingTag(
   return tags?.find((t) => t.label === ONBOARDING_TAG.label)
 }
 
-// Reuse the onboarding flag, matched by its Onboarding tag (or its name) so we
-// never grab one of the user's other flags; else create the demo flag.
 async function ensureFlag(
   store: Store,
   project: ProjectSummary,
@@ -170,7 +162,8 @@ async function ensureFlag(
   if (existing) {
     return existing
   }
-  return store
+  const isFirstFeature = !flags?.results?.length
+  const created = await store
     .dispatch(
       projectFlagService.endpoints.createProjectFlag.initiate({
         body: {
@@ -182,11 +175,12 @@ async function ensureFlag(
       }),
     )
     .unwrap()
+  if (isFirstFeature) {
+    API.trackEvent(Constants.events.CREATE_FIRST_FEATURE)
+  }
+  return created
 }
 
-// Attach the "Onboarding" tag to the demo flag (find-or-create), so the flags
-// table shows the badge from the design. Best-effort: tagging is cosmetic and
-// must never block the bootstrap.
 async function ensureOnboardingTag(
   store: Store,
   project: ProjectSummary,
@@ -215,14 +209,10 @@ async function ensureOnboardingTag(
         .unwrap()
     }
   } catch {
-    // Cosmetic only - never block onboarding on tagging.
+    // Cosmetic: tagging must never block onboarding.
   }
 }
 
-// Idempotently bring up everything the single-page flow needs: org, project,
-// Development + Production environments, and a first flag, reusing whatever
-// already exists. Split into ensure* steps so each concern is testable and the
-// reuse-vs-create decisions are obvious.
 export async function bootstrapOnboarding(
   store: Store,
   input: BootstrapInput,
@@ -234,7 +224,6 @@ export async function bootstrapOnboarding(
   if (flag) {
     await ensureOnboardingTag(store, project, flag)
   }
-  // Refresh the legacy org store so the shell sees the project.
   AppActions.refreshOrganisation()
   return {
     environment,

frontend/web/components/pages/onboarding/hooks/useOnboardingFlag.ts

@@ -41,19 +41,21 @@ export const useOnboardingFlag = (
   const { displayEnabled, isLoading, revertToggle, startToggle } =
     useFeatureRowState(state?.enabled)
 
-  const toggle = async (enabled: boolean) => {
+  const toggle = async (enabled: boolean): Promise<boolean> => {
     if (!environment || !state || !startToggle(enabled)) {
-      return
+      return false
     }
     try {
       await updateFeatureState({
         body: { enabled },
         environmentFlagId: state.id,
         environmentId: environment.api_key,
       }).unwrap()
+      return true
     } catch {
       revertToggle()
       toast('Couldn’t update your flag. Please try again.', 'danger')
+      return false
     }
   }