PostHog Analytics Plugin

import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
import posthog from 'posthog-js' // Your initialized PostHog instance

// Minimal configuration
const basicPostHogPlugin = createPostHogPlugin({
  posthogInstance: posthog, // Pass the initialized PostHog client
  debug: process.env.NODE_ENV === 'development', // See logs in console
})

// Advanced configuration example
const advancedPostHogPlugin = createPostHogPlugin<YourAppContext>({
  posthogInstance: posthog,
  eventPrefix: 'saas_onboarding_', // All events will be prefixed (e.g., 'saas_onboarding_step_active')

  // Customize specific event names
  customEventNames: {
    flowCompleted: 'saas_onboarding_signup_success',
  },

  // Enrich all events with global properties
  globalProperties: {
    app_version: '1.5.0',
    onboarding_variant: 'v2',
  },

  // Add properties to specific step types
  stepPropertyEnrichers: {
    USER_PROFILE: (step, context) => ({
      profile_form_version: '2024-03-A',
      is_premium_tier_flow: context.flowData.selectedPlan === 'premium',
    }),
    INTEGRATION_CHOICE: (step, context) => ({
      integrations_shown_count: step.payload.options.length,
    }),
  },

  // Control what data is included in events
  includeUserProperties: true, // Default: true
  includeFlowData: true, // Default: true
  includeStepMetadata: true, // Default: true
  includeSessionData: true, // Includes session ID, page URL, user agent etc.
  includePerformanceMetrics: true, // Includes step render time, memory usage, navigation time

  // Privacy & Data Filtering
  excludePersonalData: true, // Automatically redacts common PII like email, name, password
  excludeFlowDataKeys: ['apiKey', 'sensitiveAuthToken'], // Exclude specific sensitive keys from flowData
  excludeEvents: ['persistenceSuccess', 'persistenceFailure'], // Exclude certain events from tracking

  // Churn Detection
  enableChurnDetection: true,
  churnTimeoutMs: 180000, // 3 minutes idle time before 'step_abandoned' is fired
  churnRiskThreshold: 0.75, // Threshold for 'high_churn_risk' event (0-1)

  // Progress Milestones
  enableProgressMilestones: true,
  milestonePercentages: [20, 50, 80], // Fire 'progress_milestone' at these percentages

  // A/B Testing Integration
  enableExperimentTracking: true,
  experimentFlags: ['onboarding-flow-a', 'onboarding-new-ux-test'], // Monitor these feature flags for experiments

  // Performance Thresholds for 'step_render_slow' event
  performanceThresholds: {
    slowRenderMs: 1000, // Fire 'step_render_slow' if a step takes >1s to render
  },

  // Debugging
  enableConsoleLogging: true, // Log events to console before sending
})

// src/components/OnboardingProviderWrapper.tsx
'use client' // Important for Next.js App Router

import React, { useEffect } from 'react'
import { OnboardingProvider, OnboardingContext } from '@onboardjs/react'
import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
import posthog from 'posthog-js' // Your initialized PostHog client

// Define your App's custom OnboardingContext if needed
interface AppOnboardingContext extends OnboardingContext {
  currentUser?: { id: string; email?: string; name?: string; plan?: string }
  // ... other application-specific context properties
}

// Example Onboarding Steps (replace with your actual steps)
const myOnboardingSteps = [
  { id: 'welcome', type: 'INFORMATION', payload: { mainText: 'Welcome!' }, nextStep: 'profile' },
  { id: 'profile', type: 'FORM', payload: { /* form config */ }, nextStep: 'integrations' },
  { id: 'integrations', type: 'CHECKLIST', payload: { /* checklist config */ }, nextStep: 'finish' },
  { id: 'finish', type: 'CONFIRMATION', payload: { mainText: 'You\'re all set!' }, nextStep: null },
];

export default function OnboardingProviderWrapper({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  // Create the PostHog plugin instance
  const postHogPlugin = createPostHogPlugin<AppOnboardingContext>({
    posthogInstance: posthog,
    debug: process.env.NODE_ENV === 'development',
    enableChurnDetection: true,
    churnTimeoutMs: 60000, // 1 minute for quick testing
    enableProgressMilestones: true,
    milestonePercentages: [33, 66, 100],
  })

  useEffect(() => {
    // It's crucial to identify your user in PostHog once their ID is known.
    // This connects all captured events to that specific user.
    // Example: Fetch user ID from authentication state.
    const userId = 'user_abc_123'; // Replace with actual user ID
    if (userId) {
      posthog.identify(userId, {
        email: 'user@example.com',
        name: 'Jane Doe',
        plan: 'pro'
      });
    }
  }, []);

  return (
    <OnboardingProvider<AppOnboardingContext>
      steps={myOnboardingSteps}
      plugins={[postHogPlugin]} // Add the plugin here!
      // optional: initialContext={{ currentUser: { id: 'user_abc_123' }}}
    >
      {children}
    </OnboardingProvider>
  )
}

import { OnboardingEngine, OnboardingContext } from '@onboardjs/core'
import { createPostHogPlugin } from '@onboardjs/plugin-posthog'
import posthog from 'posthog-js' // Your initialized PostHog client

// Initialize PostHog if it hasn't been already (e.g., in a script tag or global init)
if (typeof window !== 'undefined' && !posthog.__loaded) {
  posthog.init('YOUR_POSTHOG_API_KEY', { api_host: 'https://app.posthog.com' });
}

// Define your App's custom OnboardingContext
interface AppOnboardingContext extends OnboardingContext {
  currentUser?: { id: string; email?: string; name?: string; plan?: string }
  // ...
}

const engine = new OnboardingEngine<AppOnboardingContext>({
  steps: [], // Your onboarding steps
  initialContext: {
    currentUser: { id: 'headless-user-456' }, // Provide initial user context
  },
})

// Install the plugin after engine creation
// Ensure `posthog` is initialized before calling createPostHogPlugin
engine.use(
  createPostHogPlugin<AppOnboardingContext>({
    posthogInstance: posthog,
    debug: true,
    enableChurnDetection: true,
  }),
)

// Don't forget to await engine.ready() before interacting with it
// await engine.ready();