Analytics Setup

Statsig Analytics

The Zeron Handbook uses Statsig for cross-product analytics and user journey tracking.

Configuration

Production: Add VITE_STATSIG_CLIENT_KEY to Vercel environment variables.

Set it to the same value as STATSIG_CLIENT_SDK_KEY (or NEXT_PUBLIC_STATSIG_CLIENT_KEY - they should be the same). This ensures cross-domain tracking works between handbook.zeron.studio and zeron.studio.

Local Development:

Create docs/.env.local:

VITE_STATSIG_CLIENT_KEY=client-your-dev-key

Or update /docs/public/statsig-init.js directly:

const statsigKey = 'client-YOUR_DEV_KEY_HERE'; // Replace with dev key

Note: Vite requires the VITE_ prefix to expose environment variables to client-side code.

What's Tracked

Automatic Tracking:

• Page Views: Every page visit with path, referrer, and title
• Anonymous Users: Generated ID stored in localStorage and cross-domain cookies
• Product Context: All events tagged with productContext: 'handbook'

User Identity:

• Anonymous ID Format: anon_<timestamp>_<random>
• Storage: localStorage + cookie (.zeron.studio domain)
• Cookie Lifetime: 1 year
• Cross-Product: Same user ID shared across all Zeron properties

Custom Event Tracking

Use the global zeronAnalytics object to track custom events:

// Log custom event
window.zeronAnalytics.logEvent('demo_clicked', {
  demo_type: 'conductor',
  page: window.location.pathname
});

// Get current user ID
const userId = window.zeronAnalytics.getUserId();

// Check if anonymous
const isAnon = window.zeronAnalytics.isAnonymous();

Event Examples

Handbook-Specific Events (to implement):

• demo_clicked - User clicked demo link
• contact_form_opened - User opened contact form
• github_link_clicked - User clicked GitHub link (if added)
• code_example_copied - User copied code example
• search_performed - User searched documentation

Cross-Product Journey

When a user visits multiple Zeron properties, their journey is stitched together:

1. User visits handbook (handbook.zeron.studio)

   • Anonymous ID generated: anon_123_abc
   • Events tracked with this ID

2. User signs in to product (e.g., feedback.zeron.studio)

   • Identity upgraded to email address
   • Event logged: user_identity_upgraded
   • All past anonymous events now linked to email

3. Full journey visible in Statsig

   • See complete path from first handbook visit to product usage
   • Attribution: Which handbook pages lead to signups?

Privacy & Compliance

Data Collection:

• Anonymous users: Generated ID only (no PII)
• No email addresses collected in handbook
• No sensitive data in event metadata

Cookie Details:

• Name: zeron_user_id
• Domain: .zeron.studio
• Max-Age: 1 year
• Secure: Yes (HTTPS only)
• SameSite: Lax

User Rights:

• Users can clear localStorage/cookies to reset
• No PII stored, so GDPR deletion not typically required for handbook

Integration with Other Products

This handbook analytics integrates with:

• Public Website (zeron.studio) - Same anonymous ID
• Feedback Service - Identity upgrade on auth
• Nexus/Conductor - (Future) Track developer engagement

See Statsig Cross-Product Analytics Strategy for full architecture.

Troubleshooting

Issue: Events not appearing in Statsig dashboard

Solutions:

• Verify API key is configured in statsig-init.js
• Check browser console for initialization errors
• Ensure HTTPS is used (required for cookies)
• Check that scripts are loading (Network tab)

Issue: Cross-domain tracking not working

Solutions:

• Verify domain is .zeron.studio (with leading dot)
• Ensure all properties use HTTPS
• Check cookie SameSite and Secure flags

Future Enhancements

Planned Analytics:

• Heat mapping for popular documentation sections
• Search analytics to improve content
• Demo click-through rates by product
• Contact form conversion rates
• Time spent on technical documentation

A/B Testing (via Statsig Feature Gates):

• Test different handbook layouts
• Optimize demo positioning
• Experiment with call-to-action placement

---

Related:

• Statsig Console
• Cross-Product Analytics Strategy
• Privacy Policy (if applicable)