Mixpanel Plugin

Mixpanel analytics plugin: track tour funnel events, step completions, and user engagement with Mixpanel properties

Overview

The Mixpanel plugin sends tour and hint events to Mixpanel, an event tracking and user analytics platform.

Installation

Install the Mixpanel peer dependency:

pnpm add mixpanel-browser

npm install mixpanel-browser

yarn add mixpanel-browser

Basic Usage

app/providers.tsx

import { AnalyticsProvider, mixpanelPlugin } from '@tour-kit/analytics'

export function Providers({ children }) {
  return (
    <AnalyticsProvider
      config={{
        plugins: [
          mixpanelPlugin({
            token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN!
          })
        ]
      }}
    >
      {children}
    </AnalyticsProvider>
  )
}

Options

Prop

Type

Event Names

Events are prefixed with TourKit: by default:

User Tour Kit Event	Mixpanel Event Name
`tour_started`	`TourKit: tour_started`
`step_viewed`	`TourKit: step_viewed`
`hint_clicked`	`TourKit: hint_clicked`

Custom Prefix

mixpanelPlugin({
  token: 'xxx',
  eventPrefix: 'App Tour - '
})

// Events: App Tour - tour_started, App Tour - step_viewed, etc.

No Prefix

mixpanelPlugin({
  token: 'xxx',
  eventPrefix: ''
})

// Events: tour_started, step_viewed, etc.

Event Properties

Events include these properties in Mixpanel:

{
  tour_id: string          // Tour identifier
  step_id?: string         // Step identifier
  step_index?: number      // Current step index (0-based)
  total_steps?: number     // Total steps in tour
  duration_ms?: number     // Duration in milliseconds
  ...metadata              // Custom metadata from event
}

User Identification

Identify users and set user properties:

app/analytics-wrapper.tsx

'use client'

import { AnalyticsProvider, mixpanelPlugin } from '@tour-kit/analytics'
import { useUser } from '@/lib/auth'

export function AnalyticsWrapper({ children }) {
  const user = useUser()

  return (
    <AnalyticsProvider
      config={{
        plugins: [
          mixpanelPlugin({
            token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN!
          })
        ],
        userId: user?.id,
        userProperties: {
          $email: user?.email,
          $name: user?.name,
          plan: user?.subscription.plan,
          signup_date: user?.createdAt
        }
      }}
    >
      {children}
    </AnalyticsProvider>
  )
}

Mixpanel supports special properties prefixed with $ like $email, $name, and $created. These are used in Mixpanel's People profiles.

Debug Mode

Enable Mixpanel's debug mode to see events in the console:

mixpanelPlugin({
  token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN!,
  debug: true
})

Debug output shows:

Events being sent
Properties included
API responses
Error messages

EU Data Residency

For EU data residency, initialize Mixpanel separately with a custom API host:

import mixpanel from 'mixpanel-browser'

// Initialize Mixpanel with EU endpoint
mixpanel.init('YOUR_TOKEN', {
  api_host: 'https://api-eu.mixpanel.com'
})

// Then use the Tour Kit plugin
<AnalyticsProvider
  config={{
    plugins: [
      mixpanelPlugin({
        token: 'YOUR_TOKEN'
      })
    ]
  }}
>
  {children}
</AnalyticsProvider>

Complete Example

app/providers.tsx

'use client'

import { AnalyticsProvider, mixpanelPlugin, consolePlugin } from '@tour-kit/analytics'
import { useUser } from '@/lib/auth'

const isDev = process.env.NODE_ENV === 'development'

export function Providers({ children }) {
  const user = useUser()

  return (
    <AnalyticsProvider
      config={{
        plugins: [
          ...(isDev ? [consolePlugin()] : []),
          mixpanelPlugin({
            token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN!,
            debug: isDev
          })
        ],
        userId: user?.id,
        userProperties: user ? {
          $email: user.email,
          $name: user.name,
          plan: user.plan,
          company: user.company
        } : undefined,
        globalProperties: {
          app_version: '1.0.0',
          platform: 'web'
        }
      }}
    >
      {children}
    </AnalyticsProvider>
  )
}

Analytics in Mixpanel

Tour Completion Funnel

Create a funnel to analyze tour completion:

Go to Insights > Funnels
Add steps:
- TourKit: tour_started
- TourKit: step_viewed (filter: step_index = 0)
- TourKit: step_viewed (filter: step_index = 1)
- TourKit: tour_completed
Group by: tour_id

Step Duration Analysis

Analyze how long users spend on each step:

Go to Insights > Insights
Event: TourKit: step_completed
Aggregate: Average of duration_ms
Group by: step_id

User Cohorts

Create cohorts based on tour behavior:

Go to Cohorts > Create Cohort
Definition: TourKit: tour_completed where tour_id = "onboarding"
Name: "Completed Onboarding"

Use this cohort to:

Compare retention between users who completed tours vs. those who didn't
Target messaging to users who skipped tours
Analyze feature adoption after tour completion

User Profiles

View tour activity on user profiles:

Go to Users > User Profile
Select a user
View Events tab
Filter by "TourKit:" to see all tour events

Retention Analysis

Track retention based on tour completion:

Go to Insights > Retention
First event: TourKit: tour_started
Return event: Any event
Segment by: tour_id

Best Practices

Use Mixpanel Special Properties

Leverage Mixpanel's special properties for better user profiles:

userProperties: {
  $email: user.email,          // Sets email in People profile
  $name: user.name,            // Sets name in People profile
  $created: user.createdAt,    // Sets signup date
  plan: user.plan              // Custom property
}

Group Properties by Context

Use Mixpanel's group analytics for B2B SaaS:

import mixpanel from 'mixpanel-browser'

// Set company context
mixpanel.set_group('company_id', 'acme-corp')

// Track with company context
mixpanelPlugin({
  token: 'YOUR_TOKEN'
})

Production Only

Avoid polluting production data with development events:

const plugins = process.env.NODE_ENV === 'production'
  ? [mixpanelPlugin({ token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN! })]
  : [consolePlugin()]

Troubleshooting

Events Not Appearing

Check these common issues:

Token is correct: Verify your Mixpanel project token
Ad blockers: Mixpanel may be blocked by ad blockers
CORS: Ensure your domain is whitelisted in Mixpanel settings
Debug mode: Enable debug mode to see console logs

mixpanelPlugin({
  token: 'YOUR_TOKEN',
  debug: true  // See events in console
})

User Not Identified

Ensure you're passing userId to the provider:

<AnalyticsProvider
  config={{
    plugins: [mixpanelPlugin({ token: 'xxx' })],
    userId: user?.id  // ✅ Required for user identification
  }}
>
  {children}
</AnalyticsProvider>

Mixpanel Documentation
Plugin Overview - Plugin architecture
AnalyticsProvider - Provider configuration

Mixpanel Plugin

On this page