PostHog Analytics Plugin

1import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
2import posthog from 'posthog-js' // Your initialized PostHog instance
3
4// Minimal configuration
5const basicPostHogPlugin = createPostHogPlugin({
6  posthogInstance: posthog, // Pass the initialized PostHog client
7  debug: process.env.NODE_ENV === 'development', // See logs in console
8})

1// Advanced configuration example
2const advancedPostHogPlugin = createPostHogPlugin<YourAppContext>({
3  posthogInstance: posthog,
4  eventPrefix: 'saas_onboarding_', // All events will be prefixed (e.g., 'saas_onboarding_step_active')
5
6  // Customize specific event names
7  customEventNames: {
8    flowCompleted: 'saas_onboarding_signup_success',
9  },
10
11  // Enrich all events with global properties
12  globalProperties: {
13    app_version: '1.5.0',
14    onboarding_variant: 'v2',
15  },
16
17  // Add properties to specific step types
18  stepPropertyEnrichers: {
19    USER_PROFILE: (step, context) => ({
20      profile_form_version: '2024-03-A',
21      is_premium_tier_flow: context.flowData.selectedPlan === 'premium',
22    }),
23    INTEGRATION_CHOICE: (step, context) => ({
24      integrations_shown_count: step.payload.options.length,
25    }),
26  },
27
28  // Control what data is included in events
29  includeUserProperties: true, // Default: true
30  includeFlowData: true, // Default: true
31  includeStepMetadata: true, // Default: true
32  includeSessionData: true, // Includes session ID, page URL, user agent etc.
33  includePerformanceMetrics: true, // Includes step render time, memory usage, navigation time
34
35  // Privacy & Data Filtering
36  excludePersonalData: true, // Automatically redacts common PII like email, name, password
37  excludeFlowDataKeys: ['apiKey', 'sensitiveAuthToken'], // Exclude specific sensitive keys from flowData
38  excludeEvents: ['persistenceSuccess', 'persistenceFailure'], // Exclude certain events from tracking
39
40  // Churn Detection
41  enableChurnDetection: true,
42  churnTimeoutMs: 180000, // 3 minutes idle time before 'step_abandoned' is fired
43  churnRiskThreshold: 0.75, // Threshold for 'high_churn_risk' event (0-1)
44
45  // Progress Milestones
46  enableProgressMilestones: true,
47  milestonePercentages: [20, 50, 80], // Fire 'progress_milestone' at these percentages
48
49  // A/B Testing Integration
50  enableExperimentTracking: true,
51  experimentFlags: ['onboarding-flow-a', 'onboarding-new-ux-test'], // Monitor these feature flags for experiments
52
53  // Performance Thresholds for 'step_render_slow' event
54  performanceThresholds: {
55    slowRenderMs: 1000, // Fire 'step_render_slow' if a step takes >1s to render
56  },
57
58  // Debugging
59  enableConsoleLogging: true, // Log events to console before sending
60})

1// src/components/OnboardingProviderWrapper.tsx
2'use client' // Important for Next.js App Router
3
4import React, { useEffect } from 'react'
5import { OnboardingProvider, OnboardingContext } from '@onboardjs/react'
6import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
7import posthog from 'posthog-js' // Your initialized PostHog client
8
9// Define your App's custom OnboardingContext if needed
10interface AppOnboardingContext extends OnboardingContext {
11  currentUser?: { id: string; email?: string; name?: string; plan?: string }
12  // ... other application-specific context properties
13}
14
15// Example Onboarding Steps (replace with your actual steps)
16const myOnboardingSteps = [
17  { id: 'welcome', type: 'INFORMATION', payload: { mainText: 'Welcome!' }, nextStep: 'profile' },
18  { id: 'profile', type: 'FORM', payload: { /* form config */ }, nextStep: 'integrations' },
19  { id: 'integrations', type: 'CHECKLIST', payload: { /* checklist config */ }, nextStep: 'finish' },
20  { id: 'finish', type: 'CONFIRMATION', payload: { mainText: 'You\'re all set!' }, nextStep: null },
21];
22
23export default function OnboardingProviderWrapper({
24  children,
25}: Readonly<{
26  children: React.ReactNode
27}>) {
28  // Create the PostHog plugin instance
29  const postHogPlugin = createPostHogPlugin<AppOnboardingContext>({
30    posthogInstance: posthog,
31    debug: process.env.NODE_ENV === 'development',
32    enableChurnDetection: true,
33    churnTimeoutMs: 60000, // 1 minute for quick testing
34    enableProgressMilestones: true,
35    milestonePercentages: [33, 66, 100],
36  })
37
38  useEffect(() => {
39    // It's crucial to identify your user in PostHog once their ID is known.
40    // This connects all captured events to that specific user.
41    // Example: Fetch user ID from authentication state.
42    const userId = 'user_abc_123'; // Replace with actual user ID
43    if (userId) {
44      posthog.identify(userId, {
45        email: 'user@example.com',
46        name: 'Jane Doe',
47        plan: 'pro'
48      });
49    }
50  }, []);
51
52  return (
53    <OnboardingProvider<AppOnboardingContext>
54      steps={myOnboardingSteps}
55      plugins={[postHogPlugin]} // Add the plugin here!
56      // optional: initialContext={{ currentUser: { id: 'user_abc_123' }}}
57    >
58      {children}
59    </OnboardingProvider>
60  )
61}

1import { OnboardingEngine, OnboardingContext } from '@onboardjs/core'
2import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
3import posthog from 'posthog-js' // Your initialized PostHog client
4
5// Initialize PostHog if it hasn't been already (e.g., in a script tag or global init)
6if (typeof window !== 'undefined' && !posthog.__loaded) {
7  posthog.init('YOUR_POSTHOG_API_KEY', { api_host: 'https://app.posthog.com' });
8}
9
10// Define your App's custom OnboardingContext
11interface AppOnboardingContext extends OnboardingContext {
12  currentUser?: { id: string; email?: string; name?: string; plan?: string }
13  // ...
14}
15
16const engine = new OnboardingEngine<AppOnboardingContext>({
17  steps: [], // Your onboarding steps
18  initialContext: {
19    currentUser: { id: 'headless-user-456' }, // Provide initial user context
20  },
21})
22
23// Install the plugin after engine creation
24// Ensure `posthog` is initialized before calling createPostHogPlugin
25engine.use(
26  createPostHogPlugin<AppOnboardingContext>({
27    posthogInstance: posthog,
28    debug: true,
29    enableChurnDetection: true,
30  }),
31)
32
33// Don't forget to await engine.ready() before interacting with it
34// await engine.ready();