Skip to main content

Analytics Setup - Complete Summary

✅ What We Built​

1. Backend System (MedusaJS v2)​

  • ✅ Custom Analytics Module (custom_analytics)
  • ✅ Three data models: AnalyticsEvent, AnalyticsSession, AnalyticsDailyStats
  • ✅ Complete CRUD workflows
  • ✅ Public tracking API (/web/analytics/track)
  • ✅ Admin APIs for querying events
  • ✅ Query parameter validation middleware
  • ✅ Privacy-focused (no PII, no cookies)

2. Client-Side Tracking (JavaScript)​

  • ✅ Lightweight tracking script (analytics.js - ~2KB)
  • ✅ Automatic pageview tracking
  • ✅ SPA navigation support (Next.js, React Router, etc.)
  • ✅ Custom event tracking API
  • ✅ Session management (30-min timeout)
  • ✅ Visitor identification (localStorage)
  • ✅ Reliable delivery (sendBeacon API)

3. Testing & Documentation​

  • ✅ 12 integration tests (all passing)
  • ✅ Complete API documentation
  • ✅ Setup guides for HTML, Next.js, React, Vue
  • ✅ Troubleshooting guides
  • ✅ Privacy & GDPR compliance docs

🔗 How Website Linking Works​

Simple & Clean Architecture:​

1. Create Website
   POST /admin/websites { domain: "example.com", name: "My Site" }
   → Returns: { id: "website_abc123" }

2. Use Website ID for Tracking
   <script data-website-id="website_abc123" ...></script>

3. Events Reference Website
   AnalyticsEvent { website_id: "website_abc123", ... }

4. Query by Website
   GET /admin/analytics-events?website_id=website_abc123

No separate analytics_id needed - we use the website's primary id directly!

📋 Quick Start Guide​

For Admins:​

  1. Create a website:

    POST /admin/websites
    {
      "domain": "example.com",
      "name": "My Website"
    }

  2. Get tracking code:

    GET /admin/websites/{id}/tracking-code

  3. Copy & paste the code into your website

  4. View analytics:

    GET /admin/analytics-events?website_id={id}

For Developers:​

<!-- Add to your website -->
<script 
  src="http://localhost:9000/analytics.js" 
  data-website-id="website_abc123"
  data-api-url="http://localhost:9000"
  defer
></script>

<!-- Track custom events -->
<button onclick="window.jytAnalytics.track('signup', { plan: 'pro' })">
  Sign Up
</button>

🎯 What's Tracked​

Automatically:​

  • ✅ Page views (including SPA navigation)
  • ✅ Referrer sources (Google, Facebook, Direct, etc.)
  • ✅ Browser & OS (parsed from user agent)
  • ✅ Device type (desktop, mobile, tablet)
  • ✅ Country (from IP, not stored)
  • ✅ Session duration (30-min timeout)
  • ✅ Unique visitors (anonymous IDs)

Manually (via API):​

  • ✅ Custom events (button clicks, form submits, etc.)
  • ✅ Custom metadata (any JSON data)

🔒 Privacy Features​

  • ❌ No cookies (uses localStorage/sessionStorage)
  • ❌ No PII (no names, emails, or personal data)
  • ❌ No IP storage (used only for geo-location, then discarded)
  • ❌ No cross-site tracking
  • ❌ No query parameters (only pathname tracked)
  • ✅ Anonymous IDs (random, not linked to users)
  • ✅ GDPR compliant (no consent required for anonymous analytics)

📊 Available Queries​

# All events for a website
GET /admin/analytics-events?website_id=abc123

# Filter by page
GET /admin/analytics-events?website_id=abc123&pathname=/products

# Filter by event type
GET /admin/analytics-events?website_id=abc123&event_type=pageview

# Filter by visitor
GET /admin/analytics-events?website_id=abc123&visitor_id=visitor_xyz

# Filter by session
GET /admin/analytics-events?website_id=abc123&session_id=session_abc

# Pagination
GET /admin/analytics-events?website_id=abc123&limit=50&offset=0

# Multiple filters
GET /admin/analytics-events?website_id=abc123&event_type=custom_event&pathname=/checkout

📁 File Structure​

jyt/
├── src/
│   ├── modules/analytics/          # Analytics module
│   │   ├── models/
│   │   │   ├── analytics-event.ts
│   │   │   ├── analytics-session.ts
│   │   │   └── analytics-daily-stats.ts
│   │   ├── service.ts
│   │   └── index.ts
│   ├── workflows/analytics/        # Workflows
│   │   ├── track-analytics-event.ts
│   │   ├── create-analytics-event.ts
│   │   ├── list-analytics-event.ts
│   │   └── ...
│   ├── api/
│   │   ├── web/analytics/track/    # Public tracking API
│   │   └── admin/
│   │       ├── analytics-events/   # Admin CRUD APIs
│   │       └── websites/
│   │           └── [id]/tracking-code/  # Get tracking code
│   └── links/                      # Module links (if needed)
├── integration-tests/
│   └── http/analytics/
│       └── track-analytics-event.spec.ts  # 12 tests ✅
└── docs/
    ├── /docs/implementation/analytics/implementation
    ├── /docs/implementation/analytics/architecture-decision
    ├── /docs/guides/analytics/website-setup
    └── ANALYTICS_SETUP_SUMMARY.md

jyt-web/
├── public/
│   └── analytics.js                # Client tracking script
└── docs/
    └── ANALYTICS_TRACKING.md       # Client-side docs

🧪 Testing​

All 12 integration tests passing:

npm run test:integration -- analytics

✅ should track a pageview event
✅ should track a custom event
✅ should create a session
✅ should parse user agent correctly
✅ should extract referrer source
✅ should handle invalid data gracefully
✅ should list analytics events via admin API
✅ should filter events by visitor_id
✅ should filter events by session_id
✅ should filter events by pathname
✅ should filter events by event_type
✅ should paginate results correctly

🚀 What's Next (Optional)​

Phase 3: Reporting APIs​

  • Dashboard overview (total views, visitors, sessions)
  • Top pages report
  • Referrer sources report
  • Browser/OS/Device breakdown
  • Real-time visitor count

Phase 4: Background Jobs​

  • Daily aggregation (populate AnalyticsDailyStats)
  • Session cleanup (close inactive sessions)
  • Data retention (archive old events)

Phase 5: Admin UI​

  • Analytics dashboard component
  • Charts and graphs
  • Date range filters
  • Export to CSV

📚 Documentation​

  1. /docs/implementation/analytics/implementation

    • Complete technical documentation
    • Data models, workflows, API endpoints
    • Privacy features and design decisions

  2. /docs/implementation/analytics/architecture-decision

    • Why we built a custom analytics system
    • Architecture decisions and trade-offs
    • Module structure and naming

  3. /docs/guides/analytics/website-setup

    • Step-by-step setup guide
    • How website linking works
    • Querying and filtering data
    • Troubleshooting

  4. ANALYTICS_TRACKING.md

    • Client-side tracking script documentation
    • Usage examples (HTML, Next.js, React, Vue)
    • Custom event tracking
    • Privacy and GDPR compliance

🎉 Summary​

You now have a fully functional, privacy-focused analytics system that:

  • ✅ Tracks pageviews and custom events
  • ✅ Works with any website (HTML, React, Vue, Next.js, etc.)
  • ✅ Respects user privacy (no cookies, no PII)
  • ✅ Provides powerful querying and filtering
  • ✅ Is fully tested and documented
  • ✅ Uses simple website ID linking (no complex setup)

The system is production-ready and can start collecting data immediately! 🚀

Just add the tracking script to your website and you're done!

Last updated on