Kordant/docs/MIXPANEL_ANALYTICS.md

ShieldAI Mixpanel Analytics Configuration

Implementation Complete ✅

The Mixpanel analytics infrastructure is fully implemented and ready for use. This document covers setup and usage.

---

What's Implemented

Backend (packages/shared-analytics)

• MixpanelService: Full implementation using Segment analytics-node SDK
• Event Taxonomy: 30+ events defined in EventType enum covering:
  • User Events: user_signed_up, user_logged_in, user_upgraded, user_downgraded
  • Subscription Events: subscription_created, subscription_updated, subscription_cancelled, subscription_renewed
  • DarkWatch Events: dark_web_scan_started, dark_web_scan_completed, exposure_detected, exposure_resolved, watchlist_item_added, watchlist_item_removed
  • VoicePrint Events: voice_enrolled, voice_analyzed, voice_match_found, synthetic_voice_detected
  • SpamShield Events: call_analyzed, sms_analyzed, spam_blocked, spam_flagged, spam_feedback_submitted
  • KPI Events: mrr_updated, conversion_occurred, churn_occurred, referral_sent, referral_converted
• User Identification: identify() and group() methods for user segmentation
• KPI Definitions: MAU, MRR, conversion rate, churn, CAC, LTV, NPS, viral coefficient
• Data Validation: Zod schema for event properties

Frontend (packages/web/src/hooks/useAnalytics.ts)

• Initialization: Auto-loads Mixpanel script via initMixpanel()
• Event Tracking: trackEvent(name, params) for generic events
• Page View Tracking: trackPageView(path, title) with automatic page title
• Waitlist Tracking: trackWaitlistSignup(email, source, tier) with Meta Pixel integration
• Multi-Platform Support: GA4, Meta Pixel, LinkedIn Insight included

---

Setup Instructions

Step 1: Create Mixpanel Account (Manual)

1. Go to https://mixpanel.com
2. Sign up for an account (free tier: 100K monthly tracked users)
3. Create a new project named "ShieldAI"
4. Copy the Project Token from Project Settings → Project Token

Step 2: Configure Backend Environment Variables

Add to ShieldAI/.env:

# Mixpanel (Backend)
MIXPANEL_TOKEN=<your-mixpanel-project-token>
MIXPANEL_API_SECRET=<optional-api-secret-for-server-side>
ANALYTICS_ENV=development  # or production, staging

Step 3: Configure Frontend Environment Variables

Create or update ShieldAI/packages/web/.env:

# Mixpanel (Frontend - Vite)
VITE_MIXPANEL_TOKEN=<same-project-token-as-backend>

Step 4: Verify Integration

Backend usage example:

import { mixpanelService, EventType } from '@shieldsai/shared-analytics';

// Track an event
await mixpanelService.track(EventType.USER_SIGNED_UP, userId, {
  plan: 'premium',
  referrer: 'google',
});

// Identify a user
await mixpanelService.identify(userId, {
  email: 'user@example.com',
  tier: 'premium',
});

Frontend usage example:

import { trackEvent, trackWaitlistSignup, trackPageView } from './hooks/useAnalytics';

// Track a page view
trackPageView('/waitlist', 'Waitlist Signup');

// Track a signup
trackWaitlistSignup('user@example.com', 'landing_page', 'free');

// Track a custom event
trackEvent('feature_used', { feature: 'darkwatch_scan', duration: 45 });

---

Event Properties Schema

All events support these standard properties (validated via Zod):

• userId (string, optional): User identifier
• sessionId (string, optional): Session identifier
• timestamp (Date, optional): Event timestamp
• platform (enum: 'web' | 'mobile' | 'desktop' | 'api', optional): Event source
• version (string, optional): App version
• environment (string, optional): deployment environment

Additional custom properties are accepted and passed through to Mixpanel.

---

KPI Definitions

KPI	Description	Calculation
MAU	Monthly Active Users	COUNT(DISTINCT userId) WHERE timestamp > NOW() - 30 DAYS
Paying Users	Active subscriptions	COUNT(DISTINCT userId) WHERE subscription.status = "active"
MRR	Monthly Recurring Revenue	SUM(subscription.amount) WHERE subscription.status = "active"
Conversion Rate	Free → Paid	COUNT(upgrade events) / COUNT(signup events)
Churn Rate	Cancellations	COUNT(cancel events) / COUNT(active subscriptions)
CAC	Customer Acquisition Cost	Total marketing spend / COUNT(new paying users)
LTV	Lifetime Value	Average subscription amount / Churn rate
NPS	Net Promoter Score	% Promoters - % Detractors
Viral Coefficient	Referral multiplier	COUNT(referral events) / COUNT(users)

---

Alert Thresholds

Configured thresholds for monitoring:

• Churn: Warning >5%, Critical >10%
• Conversion Rate: Warning <2%, Critical <1%
• MRR: Warning <90% target, Critical <80% target
• NPS: Warning <50, Critical <40
• Viral Coefficient: Warning <0.4, Critical <0.3

---

Files Modified

• packages/shared-analytics/src/config/analytics.config.ts - Event taxonomy & KPIs
• packages/shared-analytics/src/services/mixpanel.service.ts - Mixpanel service
• packages/shared-analytics/src/index.ts - Exports
• packages/web/src/hooks/useAnalytics.ts - Frontend analytics hook
• .env.example - Environment variable templates
• docs/MIXPANEL_ANALYTICS.md - This documentation

---

Next Steps

1. Create Mixpanel account (requires human action - no API for account creation)
2. Add tokens to .env files
3. Test event tracking in development
4. Set up Mixpanel dashboards for KPI monitoring
5. Configure Mixpanel alerts for threshold breaches