@mixpanel/mixpanel-wizard

Mixpanel Installation Wizard 🧙‍♂️

🚧 This package is in beta — features may change and bugs may be present. Feedback is welcome [e-mail]!

An interactive CLI tool that generates customized Mixpanel SDK installation instructions for AI-powered development environments. The wizard helps developers quickly integrate Mixpanel analytics into their applications across multiple platforms and programming languages.

Features

• Multi-Platform Support: Supports 13+ SDKs including JavaScript, Python, iOS, Android, React Native, Flutter, and more
• Interactive Setup: Guided prompts for configuration options like autocapture and session replay
• Event Templates: Pre-built event schemas for AI, e-commerce, and general applications
• AI-Optimized Output: Generates structured instructions specifically designed for AI coding assistants
• Command Line Interface: Both interactive and non-interactive modes available

Supported SDKs

JavaScript, iOS (Swift/Objective-C), Android, React Native, Flutter, Unity, Python, Ruby, PHP, Go, Java, Node.js

Usage

This guide will help you add Mixpanel analytics to your app or website using AI assistance, even if you're not a developer. The Mixpanel Installation Wizard creates step-by-step instructions that you can give to AI coding tools like Claude, ChatGPT, or Cursor.

What You'll Need

Before starting, make sure you have:

• A Mixpanel account with Admin or Owner access (sign up if you don't have one)
• Access to an AI coding assistant (Claude, ChatGPT, Cursor, etc.)
  • Be sure to use the most advanced AI model you have access to
• Your project's code files and a development or staging environment to test the changes

Step 1: Get Your Mixpanel Project Token

• Log into your Mixpanel account

• Go to your project settings (gear icon in the bottom left)

• Click on "Overview" in the left sidebar

• Scroll down to Access Keys section and copy your "Project Token" - it looks like a long string of letters and numbers

  (You will need to be an Admin or Owner in your project)

• Keep this handy - you'll need it in the next step

Step 2: Create Your AI Instructions

• Simply type npx @mixpanel/mixpanel-wizard in your terminal
• Go through and answer a few quick questions and it will then create a customized installation guide

Choose Your Settings

You'll need to pick three things:

A. Choose Your SDK Type

This depends on what type of app or website you're building:

• javascript - For websites or web apps
• react-native - For mobile apps built with React Native
• ios-swift - For iPhone/iPad apps (Swift)
• ios-objective-c - For iPhone/iPad apps (Objective-C)
• android - For Android mobile apps
• python - For Python applications
• nodejs - For Node.js backend applications
• flutter - For Flutter mobile apps
• unity - For Unity games
• go - For Go applications
• ruby - For Ruby applications
• php - For PHP applications
• java - For Java applications

Don't see your platform? Check with a developer or choose the closest match.

B. Choose Your Event Type

This determines what kinds of user actions you'll track:

• ai - Best for AI-powered features (chatbots, AI tools, ML features)
• ecommerce - Best for online stores and shopping apps
• default - Good general-purpose events for most other apps

C. Decide on Extra Features

• Autocapture - Automatically tracks clicks and page views (JavaScript SDK only)
• Session Replay - Records user sessions for debugging (JavaScript, iOS Swift, Android SDKs only)

Recommendation: Enable both if they're available for your platform

Step 3: Give Instructions to Your AI Assistant

• Open your AI coding tool (Claude, ChatGPT, Cursor, etc.).
• Copy over the instruction file generated from the step2 to your project.
• Make sure it has access to your project files
• Next, copy and paste this prompt into your AI Agent

Let's set up Mixpanel.
1. Set up mixpanel by following the steps in MIXPANEL_INSTALLATION_INSTRUCTIONS.txt. Make sure to follow the global rules specified in the MIXPANEL_INSTALLATION_INSTRUCTIONS.txt.
2. After completing the steps in the installation guide, delete the MIXPANEL_INSTALLATION_INSTRUCTIONS.txt

• Let the AI complete all the steps

The AI will:

• Follow the generated setup instructions
• Install the necessary code
• Set up tracking for your chosen events

Step 4: Test Your Installation

After the AI completes the setup, test that everything is working:

Quick Test

• Deploy the changes to your testing environment
• Use your app or website normally
• Go to your Mixpanel dashboard
• Click on "Events" in the left sidebar or visit the Events page
• You should see events flowing in as you use your app (you may need to refresh Mixpanel)

What to Look For

Depending on your event type, you should see:

For AI events:

• "Launch AI" when AI features are used
• "AI Prompt Sent" when users send prompts
• "AI Response Sent" when AI responds

For E-commerce events:

• "Product Viewed" when products are viewed
• "Add to Cart" when items are added to cart
• "Purchase" when transactions complete

For Default events:

• "Sign Up" for new user registrations
• "Page View" for page visits
• "Search" for search queries

Troubleshooting

No Events Showing Up?

• Check that you used the correct project token
• Verify your app is running and being used
• Wait a few minutes - sometimes there's a delay
• Check the browser console (F12) for any error messages

Wrong Events Tracking?

• Make sure you chose the right event type in Step 2B
• Ask your AI assistant to show you what events are being tracked
• You can always re-run the setup with different event types

Need Help?

• Check the Mixpanel documentation at docs.mixpanel.com
• Ask your AI assistant to explain what it installed
• Contact Mixpanel support through our help center

Success! 🎉

Once you see events flowing into your Mixpanel dashboard, you're all set! You can now:

• View real-time user activity
• Create reports and dashboards
• Set up alerts for important events
• Analyze user behavior patterns

The AI has set up all the technical details for you - now you can focus on understanding your users and growing your product.

Command Line Mode

Skip the interactive prompts by providing options directly:

# Basic usage
mixpanel-wizard --token YOUR_TOKEN --sdk javascript --events ai

# With additional options
mixpanel-wizard --token YOUR_TOKEN --sdk javascript --autocapture --sessionreplay --events ecommerce

# With approval for each code change
mixpanel-wizard --token YOUR_TOKEN --sdk javascript --confirm-each --events ai

# iOS with specific package manager
mixpanel-wizard --token YOUR_TOKEN --sdk ios-swift --events default

Available Options

Option	Description	Values
-t, --token	Your Mixpanel project token	String
--sdk	SDK type to install	javascript, flutter, ios-objective-c, ios-swift, android, react-native, go, python, ruby, php, nodejs,java, unity
--events	Additional event type options	ai, ecommerce, default
--autocapture	Enable autocapture (JavaScript only)	Boolean flag
--sessionreplay	Enable session replay (Javascript, iOS Swift and Android Only)	Boolean flag
--confirm-each	Require approval for each code change made by AI	Boolean flag

Output

The wizard generates a MIXPANEL_INSTALLATION_INSTRUCTIONS.txt file containing:

• Step 1: SDK Installation - Platform-specific installation commands and configuration
• Step 2: User Identification - Code snippets for identifying users
• Step 3: Event Tracking - Implementation examples and event templates
• Best Practices - Security guidelines and recommendations

Simply provide the prompt from MIXPANEL_INSTALLATION_INSTRUCTIONS.txt to your AI coding agent.

Example Output Structure

You are a code-mod assistant tasked with adding Mixpanel analytics...

Global Rules
1. Ask before doing: When in doubt, ask for confirmation.
2. One small change at a time: Propose changes in small, reviewable steps.
...

Step 1: Install the Mixpanel SDK for javascript.
To install the Javascript SDK, paste the following code snippet...

Step 2: Identify your users to Mixpanel...
mixpanel.identify('USER_ID')
mixpanel.people.set({ '$name': 'Jane Doe'...

Step 3: Track events using the Mixpanel SDK...
Events and associated properties:
{
    eventName: "Launch AI",
    description: "Tracks when a user launches an AI-powered feature...",
    properties: []
}
...

Event Templates

Default Events

• Sign Up: Track new user acquisition with signup method and UTM parameters
• Sign In: Monitor user login events with authentication method tracking
• Page View: Track page/screen views with URL and title information
• Search: Capture search queries and result counts
• Error: Monitor application errors with error types and messages
• Purchase: Track completed transactions with revenue and currency data
• Conversion: Monitor key value moments specific to your product type

AI Events

• Launch AI: Track AI feature engagement and measure adoption patterns
• AI Prompt Sent and Prompt Text: Capture user prompts and analyze engagement intent
• AI Response Sent: Monitor AI outputs with cost, token usage, and response time metrics
• API Error: Track AI feature errors and monitor failure rates
• User Feedback: Collect user sentiment and feedback on AI interactions
• AI Dismissed: Monitor AI feature disengagement points
• Conversion Event: Measure how AI features influence key business outcomes

E-commerce Events

• Purchase: Track completed transactions with cart contents and total price
• Add to Cart: Monitor shopping behavior with cart items and product categories
• Product Viewed: Track product engagement across the purchasing funnel
• Ad Data: Monitor advertising spend and cost data for ROI calculations

License

This project is licensed under the Apache License - see the LICENSE.md file for details.

Support

• Documentation: Mixpanel Developer Docs
• Issues: GitHub Issues
• Community: Mixpanel Community

⚠️ Important: This tool generates AI-optimized installation instructions. Always review and test the generated code before deploying to production. Human oversight is strongly recommended for all integrations.