chore(shared,ui): Add telemetry event for flow steps (#8951)

Author: LauraBeatris

.changeset/gold-ends-throw.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Add a generic `FLOW_STEP_MOUNTED` telemetry event (`eventFlowStepMounted`) for measuring multi-step flow funnels, and wire it into the self-serve SSO flow

packages/shared/src/telemetry/events/flow-step.ts

@@ -0,0 +1,40 @@
+import type { TelemetryEventRaw } from '../../types';
+
+const EVENT_FLOW_STEP_MOUNTED = 'FLOW_STEP_MOUNTED';
+const EVENT_SAMPLING_RATE = 1;
+
+type EventFlowStepMounted = {
+  /** The flow the step belongs to, e.g. `configureSSO` (mirrors `Flow.Root`'s `flow`). */
+  flow: string;
+  /** The step/part that mounted, e.g. `verify-domain` */
+  step: string;
+  /** Free-form, flow-specific metadata supplied by the caller (e.g. `timestamp`, `connectionStatus`). */
+  metadata: TelemetryEventRaw['payload'];
+} & TelemetryEventRaw['payload'];
+
+/**
+ * Fires an event from a part of a multi-step flow.
+ *
+ * @param flow - The flow identifier (matches `Flow.Root`'s `flow`).
+ * @param step - The step/part that mounted.
+ * @param metadata - Flow-specific metadata sent under `payload.metadata`.
+ * @param eventSamplingRate - Override the default full-capture sampling rate.
+ * @example
+ * telemetry.record(eventFlowStepMounted('configureSSO', 'verify-domain', { timestamp: new Date().toISOString(), connectionStatus: 'unconfigured' }));
+ */
+export function eventFlowStepMounted(
+  flow: string,
+  step: string,
+  metadata: TelemetryEventRaw['payload'] = {},
+  eventSamplingRate: number = EVENT_SAMPLING_RATE,
+): TelemetryEventRaw<EventFlowStepMounted> {
+  return {
+    event: EVENT_FLOW_STEP_MOUNTED,
+    eventSamplingRate,
+    payload: {
+      flow,
+      step,
+      metadata,
+    },
+  };
+}

packages/shared/src/telemetry/events/index.ts

@@ -1,4 +1,5 @@
 export * from './component-mounted';
+export * from './flow-step';
 export * from './method-called';
 export * from './framework-metadata';
 export * from './theme-usage';

packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx

@@ -1,3 +1,6 @@
+import { useClerk, useOrganization } from '@clerk/shared/react';
+import { eventFlowStepMounted } from '@clerk/shared/telemetry';
+
 import { Button, Col, descriptors, Flex, Flow, Heading, Icon, localizationKeys, Text } from '@/customizables';
 import { useCardState } from '@/elements/contexts';
 import { ChevronRight, DuotoneShieldCheck } from '@/icons';
@@ -15,6 +18,8 @@ export const ActivateStep = (): JSX.Element => {
     onExit,
   } = useConfigureSSO();
   const card = useCardState();
+  const clerk = useClerk();
+  const { organization } = useOrganization();
 
   // The activate step is only reachable with a configured connection, so the
   // domains are set; join multiples for the subtitle copy.
@@ -31,6 +36,14 @@ export const ActivateStep = (): JSX.Element => {
 
     try {
       await setConnectionActive(enterpriseConnection.id, true);
+      clerk.telemetry?.record(
+        eventFlowStepMounted('configureSSO', 'activate', {
+          timestamp: new Date().toISOString(),
+          connectionStatus: 'active',
+          connectionId: enterpriseConnection.id,
+          organizationId: organization?.id ?? null,
+        }),
+      );
       onExit?.();
     } catch (err) {
       handleError(err as Error, [], card.setError);

packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx

@@ -1,7 +1,8 @@
-import { useUser } from '@clerk/shared/react';
+import { useClerk, useOrganization, useUser } from '@clerk/shared/react';
+import { eventFlowStepMounted } from '@clerk/shared/telemetry';
 import type { OrganizationDomainResource } from '@clerk/shared/types';
 import type React from 'react';
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 import {
   Badge,
@@ -40,14 +41,35 @@ export const OrganizationDomainsStep = (): JSX.Element => {
   const {
     enterpriseConnection,
     organizationDomains,
+    organizationEnterpriseConnection,
     contentRef,
     organizationDomainMutations: { createDomain, revalidate },
     enterpriseConnectionMutations: { updateConnection },
   } = useConfigureSSO();
   const { goPrev, goNext, isFirstStep, isLastStep } = useWizard();
   const card = useCardState();
+  const clerk = useClerk();
+  const { organization } = useOrganization();
   const [domainToRemove, setDomainToRemove] = useState<OrganizationDomainResource | null>(null);
 
+  const hasRecordedTelemetryEvent = useRef(false);
+  useEffect(() => {
+    if (hasRecordedTelemetryEvent.current) {
+      return;
+    }
+
+    hasRecordedTelemetryEvent.current = true;
+    clerk.telemetry?.record(
+      eventFlowStepMounted('configureSSO', 'verify-domain', {
+        timestamp: new Date().toISOString(),
+        connectionStatus: organizationEnterpriseConnection.status,
+        connectionId: enterpriseConnection?.id ?? null,
+        organizationId: organization?.id ?? null,
+      }),
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   const handleCreateDomain = async (domain: string) => {
     card.setError(undefined);