feat(onboarding): track dashboard exploration (#3050)

* feat(onboarding): track dashboard exploration

* fix(onboarding): scope dashboard exploration event

* fix(onboarding): buffer dashboard exploration tracking

* fix(onboarding): track demo dashboard exploration

* test(onboarding): bound demo exploration assertion

* test(onboarding): require demo exploration signal

Author: WcaleNieWolny

src/components/Sidebar.vue

@@ -18,6 +18,7 @@ import { useMainStore } from '~/stores/main'
 import {
   allowOnboardingDashboardExploration,
   getOnboardingResumeAppId,
+  ONBOARDING_DASHBOARD_EXPLORED_EVENT,
   shouldConfirmOnboardingDashboardExploration,
 } from '~/utils/onboardingRedirect'
 import DropdownProfile from '../components/dashboard/DropdownProfile.vue'
@@ -96,6 +97,7 @@ async function openTab(tab: Tab) {
     if (dialogStore.lastButtonRole !== 'primary')
       return
 
+    window.dispatchEvent(new Event(ONBOARDING_DASHBOARD_EXPLORED_EVENT))
     allowOnboardingDashboardExploration(onboardingUserId, onboardingResumeAppId)
   }
 

src/components/dashboard/AppOnboardingFlow.vue

@@ -48,7 +48,7 @@ import {
   loadOnboardingAppDraft,
 } from '~/utils/onboardingAppDraft'
 import { createOnboardingDetailsFieldDebouncer, createOnboardingProgressTracker } from '~/utils/onboardingProgressAnalytics'
-import { allowOnboardingDashboardExploration } from '~/utils/onboardingRedirect'
+import { allowOnboardingDashboardExploration, ONBOARDING_DASHBOARD_EXPLORED_EVENT } from '~/utils/onboardingRedirect'
 import { slugifyOnboardingSegment } from '~/utils/onboardingSlug'
 import AppOnboardingIconInput from './AppOnboardingIconInput.vue'
 
@@ -286,6 +286,7 @@ const setupTitle = computed(() => usesBuilderSetupCommand.value ? t('unified-onb
 const setupSubtitle = computed(() => usesBuilderSetupCommand.value ? t('unified-onboarding-setup-builder-subtitle') : t('unified-onboarding-setup-ota-subtitle'))
 
 let progressTracker: ReturnType<typeof createOnboardingProgressTracker> | null = null
+let pendingDashboardExplored = false
 
 function trackV2DetailsEvent(name: OnboardingDetailsEvent, details: OnboardingDetailsEventProperties = {}) {
   if (props.preOrg)
@@ -306,6 +307,8 @@ function initializeProgressTracking(resumed: boolean) {
     supaHost: config.supaHost,
   })
   progressTracker.viewStep(flowStep.value)
+  if (pendingDashboardExplored)
+    trackDashboardExplored()
 }
 
 function completeAndViewStep(nextStep: OnboardingFlowStep, completionProperties: OnboardingStepCompletionProperties = {}) {
@@ -1010,6 +1013,7 @@ async function seedDemoData() {
       throw error
     }
 
+    window.dispatchEvent(new Event(ONBOARDING_DASHBOARD_EXPLORED_EVENT))
     allowOnboardingDashboardExploration(onboardingUserId.value, createdApp.value.app_id)
     dashboardAppsStore.upsertApp({
       app_id: createdApp.value.app_id,
@@ -1124,11 +1128,22 @@ function openDashboard() {
       appId: createdApp.value.app_id,
     })
   }
+  window.dispatchEvent(new Event(ONBOARDING_DASHBOARD_EXPLORED_EVENT))
   allowOnboardingDashboardExploration(onboardingUserId.value, createdApp.value.app_id)
   router.push(`/app/${encodeURIComponent(createdApp.value.app_id)}/getting-started`)
 }
 
+function trackDashboardExplored() {
+  if (!progressTracker) {
+    pendingDashboardExplored = true
+    return
+  }
+  pendingDashboardExplored = false
+  progressTracker?.trackDashboardExplored(createdApp.value?.app_id)
+}
+
 onMounted(async () => {
+  window.addEventListener(ONBOARDING_DASHBOARD_EXPLORED_EVENT, trackDashboardExplored)
   let resumedFlow = false
   isLoading.value = true
   try {
@@ -1162,6 +1177,7 @@ onMounted(async () => {
 })
 
 onBeforeUnmount(() => {
+  window.removeEventListener(ONBOARDING_DASHBOARD_EXPLORED_EVENT, trackDashboardExplored)
   detailsFieldTracker.dispose()
 
   if (localIconPreview.value.startsWith('blob:'))

src/utils/onboardingProgressAnalytics.ts

@@ -206,9 +206,23 @@ export function createOnboardingProgressTracker(options: CreateOnboardingProgres
     return eventProperties
   }
 
+  function trackDashboardExplored(appId?: string) {
+    if (!activeStep)
+      return
+
+    const properties = sharedProperties(activeStep)
+    if (!properties)
+      return
+    if (appId)
+      properties.app_id = appId
+
+    safelyCapture('onboarding_dashboard_explored', properties)
+  }
+
   return {
     completeStep,
     trackCopyEvent,
+    trackDashboardExplored,
     trackDetailsEvent,
     viewStep,
   }

src/utils/onboardingRedirect.ts

@@ -1,5 +1,6 @@
 // August uses Central European Summer Time (UTC+2).
 export const ONBOARDING_REDIRECT_CUTOFF = Date.parse('2026-08-04T01:00:00+02:00')
+export const ONBOARDING_DASHBOARD_EXPLORED_EVENT = 'capgo:onboarding-dashboard-explored'
 
 const DASHBOARD_EXPLORATION_STORAGE_KEY = 'capgo:onboarding-dashboard-exploration'
 

tests/app-onboarding-progress-integration.unit.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
 
 const onboardingSource = readFileSync(new URL('../src/components/dashboard/AppOnboardingFlow.vue', import.meta.url), 'utf8')
+const sidebarSource = readFileSync(new URL('../src/components/Sidebar.vue', import.meta.url), 'utf8')
 
 function sourceBetween(start: string, end: string) {
   return onboardingSource.slice(onboardingSource.indexOf(start), onboardingSource.indexOf(end))
@@ -92,5 +93,19 @@ describe('app onboarding progress analytics integration', () => {
     expect(dashboardExit).toContain('appId: createdApp.value.app_id')
     expect(dashboardExit).toContain('/getting-started')
     expect(dashboardExit.indexOf('completeStep')).toBeLessThan(dashboardExit.indexOf('router.push'))
+    expect(dashboardExit).toContain('window.dispatchEvent(new Event(ONBOARDING_DASHBOARD_EXPLORED_EVENT))')
+    expect(onboardingSource).toContain('progressTracker?.trackDashboardExplored(createdApp.value?.app_id)')
+    expect(onboardingSource).toContain('window.addEventListener(ONBOARDING_DASHBOARD_EXPLORED_EVENT, trackDashboardExplored)')
+    expect(onboardingSource).toContain('window.removeEventListener(ONBOARDING_DASHBOARD_EXPLORED_EVENT, trackDashboardExplored)')
+    expect(onboardingSource).toContain('pendingDashboardExplored = true')
+    expect(onboardingSource).toContain('if (pendingDashboardExplored)')
+
+    const demoExit = sourceBetween('async function seedDemoData()', 'async function copyText(')
+    expect(demoExit).toContain('window.dispatchEvent')
+    expect(demoExit).toContain('allowOnboardingDashboardExploration')
+    expect(demoExit.indexOf('window.dispatchEvent')).toBeLessThan(demoExit.indexOf('allowOnboardingDashboardExploration'))
+
+    const confirmedSidebarExit = sidebarSource.slice(sidebarSource.indexOf('if (requiresOnboardingExplorationConfirmation)'), sidebarSource.indexOf('if (tab.onClick)'))
+    expect(confirmedSidebarExit.indexOf("lastButtonRole !== 'primary'")).toBeLessThan(confirmedSidebarExit.indexOf('window.dispatchEvent(new Event(ONBOARDING_DASHBOARD_EXPLORED_EVENT))'))
   })
 })

tests/onboarding-progress-analytics.unit.test.ts

@@ -176,6 +176,33 @@ describe('onboarding progress analytics', () => {
     expect(properties).toEqual(capture.mock.calls[0]?.[2])
   })
 
+  it.concurrent('captures dashboard exploration with the active onboarding attempt context', () => {
+    const capture = vi.fn()
+    const tracker = createOnboardingProgressTracker({
+      capture,
+      flow: 'pre_org',
+      resumed: true,
+      steps,
+      supaHost: 'https://supabase.capgo.test',
+    })
+    tracker.viewStep('setup')
+    capture.mockClear()
+
+    tracker.trackDashboardExplored('com.example.app')
+
+    expect(capture).toHaveBeenCalledWith(
+      'onboarding_dashboard_explored',
+      'https://supabase.capgo.test',
+      expect.objectContaining({
+        app_id: 'com.example.app',
+        onboarding_attempt_id: expect.any(String),
+        onboarding_version: ONBOARDING_ANALYTICS_VERSION,
+        resumed: true,
+        step: 'setup',
+      }),
+    )
+  })
+
   it.concurrent('deduplicates completion for one visit and resets timing after back navigation', () => {
     let now = 10
     const capture = vi.fn()

tests/onboarding-redirect.unit.test.ts

@@ -77,6 +77,17 @@ describe('onboarding dashboard redirect', () => {
     expect(refreshedModule.getOnboardingResumeRedirect({ appId: 'com.example.app', appCount: 1, createdAt: eligibleUser, organizationCount: 1, path: '/apps', resumeAppId: null, userId: 'user-1' })).toBeNull()
   })
 
+  it('keeps the shared exploration grant free of analytics signals', async () => {
+    const module = await import('../src/utils/onboardingRedirect.ts')
+    const listener = vi.fn()
+    window.addEventListener(module.ONBOARDING_DASHBOARD_EXPLORED_EVENT, listener)
+
+    module.allowOnboardingDashboardExploration('user-1', 'com.example.app')
+
+    expect(listener).not.toHaveBeenCalled()
+    window.removeEventListener(module.ONBOARDING_DASHBOARD_EXPLORED_EVENT, listener)
+  })
+
   it('ignores a null grant so a missing user id cannot clear exploration', async () => {
     const module = await import('../src/utils/onboardingRedirect.ts')
     module.allowOnboardingDashboardExploration('user-1', 'com.example.app')