feat: event tracking happy path

comatory · comatory · commit f92bb557a4a5 · 2026-04-15T20:51:45.000+02:00
diff --git a/studio/src/components/onboarding/onboarding-provider.tsx b/studio/src/components/onboarding/onboarding-provider.tsx
@@ -40,7 +40,7 @@ export const OnboardingContext = createContext<OnboardingState>({
   resetSkipped: () => undefined,
 });
 
-const ONBOARDING_V1_LAST_STEP = 4;
+const ONBOARDING_V1_LAST_STEP = 3;
 
 export const OnboardingProvider = ({ children }: { children: ReactNode }) => {
   const { onboarding: onboardingFlag, status: featureFlagStatus } = useContext(PostHogFeatureFlagContext);
diff --git a/studio/src/components/onboarding/step-1.tsx b/studio/src/components/onboarding/step-1.tsx
@@ -1,5 +1,6 @@
 import { useEffect } from 'react';
 import { useOnboarding } from '@/hooks/use-onboarding';
+import { usePostHog } from 'posthog-js/react';
 import { OnboardingContainer } from './onboarding-container';
 import { OnboardingNavigation } from './onboarding-navigation';
 import { useMutation } from '@connectrpc/connect-query';
@@ -8,6 +9,7 @@ import { useRouter } from 'next/router';
 import { EnumStatusCode } from '@wundergraph/cosmo-connect/dist/common/common_pb';
 import { useToast } from '../ui/use-toast';
 import { SubmitHandler, useZodForm } from '@/hooks/use-form';
+import { captureOnboardingEvent } from '@/lib/track';
 import { Controller } from 'react-hook-form';
 import { z } from 'zod';
 import { Form } from '../ui/form';
@@ -33,10 +35,21 @@ const WhyListItem = ({ title, text }: { title: string; text: string }) => (
   </li>
 );
 
+const normalizeReferrer = (referrer: string | string[]): string => {
+  if (Array.isArray(referrer)) {
+    return referrer.join(' ');
+  }
+
+  return referrer;
+};
+
 export const Step1 = () => {
   const router = useRouter();
+  const posthog = usePostHog();
   const { toast } = useToast();
   const { setStep, setSkipped, setOnboarding, onboarding } = useOnboarding();
+  // Referrer can be `wgc` when onboarding is opened via `wgc demo` command
+  const referrer = normalizeReferrer(router.query.referrer || document.referrer);
 
   const form = useZodForm<OnboardingFormValues>({
     mode: 'onChange',
@@ -63,6 +76,12 @@ export const Step1 = () => {
         slack: formValues.channels.slack,
         email: formValues.channels.email,
       });
+      captureOnboardingEvent(posthog, {
+        name: 'onboarding_step_completed',
+        options: {
+          step_name: 'welcome',
+        },
+      });
       router.push('/onboarding/2');
     },
     onError: (error) => {
@@ -82,7 +101,21 @@ export const Step1 = () => {
 
   useEffect(() => {
     setStep(1);
-  }, [setStep]);
+  }, [setStep, posthog, referrer]);
+
+  useEffect(() => {
+    // We want to trigger the onboarding only for the first time when the onboarding record
+    // does not exist in the database yet. Users can navigate to this first step as well
+    // and in that case we want to ignore it.
+    if (onboarding) return;
+
+    captureOnboardingEvent(posthog, {
+      name: 'onboarding_started',
+      options: {
+        entry_source: referrer,
+      },
+    });
+  }, [onboarding, referrer, posthog]);
 
   return (
     <OnboardingContainer>
@@ -151,7 +184,15 @@ export const Step1 = () => {
       </div>
 
       <OnboardingNavigation
-        onSkip={setSkipped}
+        onSkip={() => {
+          captureOnboardingEvent(posthog, {
+            name: 'onboarding_skipped',
+            options: {
+              step_name: 'welcome',
+            },
+          });
+          setSkipped();
+        }}
         forwardLabel="Start the tour"
         forward={{
           onClick: form.handleSubmit(onSubmit),
diff --git a/studio/src/components/onboarding/step-2.tsx b/studio/src/components/onboarding/step-2.tsx
@@ -5,7 +5,9 @@ import { getFederatedGraphByName } from '@wundergraph/cosmo-connect/dist/platfor
 import { EnumStatusCode } from '@wundergraph/cosmo-connect/dist/common/common_pb';
 import { GetFederatedGraphByNameResponse } from '@wundergraph/cosmo-connect/dist/platform/v1/platform_pb';
 import { CheckCircledIcon, InfoCircledIcon } from '@radix-ui/react-icons';
+import { usePostHog } from 'posthog-js/react';
 import { useOnboarding } from '@/hooks/use-onboarding';
+import { captureOnboardingEvent } from '@/lib/track';
 import { OnboardingContainer } from './onboarding-container';
 import { OnboardingNavigation } from './onboarding-navigation';
 import { FederationAnimation } from './federation-animation';
@@ -118,6 +120,7 @@ const StatusText = ({ status, onRetry }: { status: 'pending' | 'ok' | 'fail' | '
 export const Step2 = () => {
   const { setStep, setSkipped } = useOnboarding();
   const router = useRouter();
+  const posthog = usePostHog();
   const [isPolling, setIsPolling] = useState(true);
   const [pollingEpoch, setPollingEpoch] = useState(0);
 
@@ -225,10 +228,26 @@ export const Step2 = () => {
 
       <OnboardingNavigation
         className="pt-2"
-        onSkip={setSkipped}
+        onSkip={() => {
+          captureOnboardingEvent(posthog, {
+            name: 'onboarding_skipped',
+            options: {
+              step_name: 'create_graph',
+            },
+          });
+          setSkipped();
+        }}
         backHref="/onboarding/1"
         forward={{
-          onClick: () => router.push('/onboarding/3'),
+          onClick: () => {
+            captureOnboardingEvent(posthog, {
+              name: 'onboarding_step_completed',
+              options: {
+                step_name: 'create_graph',
+              },
+            });
+            router.push('/onboarding/3');
+          },
           disabled: status !== 'ok',
         }}
       />
diff --git a/studio/src/components/onboarding/step-3.tsx b/studio/src/components/onboarding/step-3.tsx
@@ -2,6 +2,8 @@ import { motion } from 'framer-motion';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useOnboarding } from '@/hooks/use-onboarding';
 import { useFireworks } from '@/hooks/use-fireworks';
+import { usePostHog } from 'posthog-js/react';
+import { captureOnboardingEvent } from '@/lib/track';
 import { OnboardingContainer } from './onboarding-container';
 import { OnboardingNavigation } from './onboarding-navigation';
 import { StatusIcon, type OnboardingStatus } from './status-icon';
@@ -100,6 +102,7 @@ export const Step3 = () => {
   const { toast } = useToast();
   const { setStep, setSkipped, setOnboarding } = useOnboarding();
   const currentOrg = useCurrentOrganization();
+  const posthog = usePostHog();
 
   const [isPolling, setIsPolling] = useState(true);
   const [isMetricsPolling, setIsMetricsPolling] = useState(false);
@@ -139,7 +142,11 @@ export const Step3 = () => {
 
   const hasActiveRouter = (routersData?.routers?.length ?? 0) > 0;
 
-  const metricsStatus = getMetricsStatus({ data: graphData, isPolling: isMetricsPolling, hasPolled: hasMetricsPolled });
+  const metricsStatus = getMetricsStatus({
+    data: graphData,
+    isPolling: isMetricsPolling,
+    hasPolled: hasMetricsPolled,
+  });
 
   useFireworks(metricsStatus === 'ok');
 
@@ -186,6 +193,12 @@ export const Step3 = () => {
         email: Boolean(prev?.email),
       }));
 
+      captureOnboardingEvent(posthog, {
+        name: 'onboarding_completed',
+        options: {
+          step_name: 'run_router_send_metrics',
+        },
+      });
       setIsFinished(true);
     },
     onError: (error) => {
@@ -332,7 +345,15 @@ export const Step3 = () => {
 
             <OnboardingNavigation
               className="pt-2"
-              onSkip={setSkipped}
+              onSkip={() => {
+                captureOnboardingEvent(posthog, {
+                  name: 'onboarding_skipped',
+                  options: {
+                    step_name: 'run_router_send_metrics',
+                  },
+                });
+                setSkipped();
+              }}
               backHref="/onboarding/2"
               forward={{
                 onClick: () => mutate({}),
diff --git a/studio/src/lib/track.ts b/studio/src/lib/track.ts
@@ -1,7 +1,7 @@
 // Tracking. This will be available if the following scripts are embedded though CUSTOM_HEAD_SCRIPTS
 // Reo, PostHog
 
-import posthog from 'posthog-js';
+import posthog, { type PostHog } from 'posthog-js';
 
 declare global {
   interface Window {
@@ -79,4 +79,56 @@ const identify = ({
   });
 };
 
-export { resetTracking, identify };
+/**
+ * IDs in this type are ordered. They correspond to [cosmo-onboarding-v1] onboarding version
+ */
+type OnboardingStepId = 'welcome' | 'create_graph' | 'run_router_send_metrics';
+type OnboardingTrackEvent =
+  | {
+      name: 'onboarding_started';
+      options: {
+        entry_source: string;
+      };
+    }
+  | {
+      name: 'onboarding_step_completed';
+      options: {
+        step_name: OnboardingStepId;
+      };
+    }
+  | {
+      name: 'onboarding_skipped';
+      options: {
+        step_name: OnboardingStepId;
+      };
+    }
+  | {
+      name: 'onboarding_step_failed';
+      options: {
+        step_name: OnboardingStepId;
+        entry_source: string;
+        /**
+         * + [resource] - CRUD operation failures, such as onboarding record created
+         *   in the database, updating communication channels, creating federated
+         *   graph & plugin publish (CLI)
+         * + [router] - failures when running the router via CLI
+         * + [metrics] - sending metrics fails (CLI) or metrics are not detected
+         *   within permitted time window (web)
+         * + [invites] - failed to send invites after finishing the onboarding
+         */
+        error_category: 'resource_created' | 'router' | 'metrics' | 'invites';
+        error_message: string;
+      };
+    }
+  | {
+      name: 'onboarding_completed';
+      options: {
+        step_name: OnboardingStepId;
+      };
+    };
+
+const captureOnboardingEvent = (client: PostHog, event: OnboardingTrackEvent): void => {
+  client.capture(event.name, event.options);
+};
+
+export { resetTracking, identify, captureOnboardingEvent };
