PostHog Product Analytics Specification

Purpose & Scope

This specification defines the implementation of PostHog for frontend product analytics, user behaviour tracking, and session recording for the Digital Lock On PWA.

PostHog will track user interactions within the modal-heavy PWA interface, providing insights into workflow completion rates, user journeys, and UX friction points that cannot be captured through traditional pageview analytics.

Requirements Implemented

• REQ-ANALYTICS-001: Product Analytics and System Monitoring - Frontend analytics requirements

Related Decisions

• [ ] To be created: ADR-XXX: Analytics and Monitoring Tool Selection

Architecture Overview

PostHog JavaScript SDK will be integrated into the React PWA to provide:

• Automatic pageview and click tracking
• Custom event tracking for modal workflows
• User identification and session tracking
• Session recordings for UX analysis
• Feature flags for controlled rollouts
• Offline event queuing with sync on reconnection

Integration Points

Automatic Capture:

• Pageviews (including virtual pageviews for modals)
• Button clicks
• Form interactions
• Link clicks

Custom Events:

• Modal lifecycle (open, complete, abandon)
• Workflow completions (lock-on, handover, protection changes)
• QR code scans
• Error encounters
• Offline/online state changes

Implementation Details

Installation & Configuration

1. Install PostHog SDK
2. Setup automated monitoring
3. Setup custom events

Core Events to Track

Modal Lifecycle Events

These prove the core workflows are functioning:

1. protection_activated - PWA activated
2. protection_authorised - PWA authorised
3. protection_deactivated - PWA handed back
4. session_conflict - User signed in on other device
5. session_conflict_handover - User continued on other device
6. session_conflict_cancelled - User cancelled signed in on other device
7. worksite_enabled - Worksite enabled (Protector locked on)
8. worksite_disabled - Worksite disabled (Protector locked off)
9. worker_qr_locked_on - Worker signed on
10. worker_qr_locked_off - Worker signed off (shift ended)
11. worker_manually_locked_on - Manual lock on
12. worker_manually_locked_off - Manual lock off
13. worker_locked_off_returning - Locked off returning to site (shift not ended)
14. worker_forced_lock_off - Force lock off
15. worker_competencies_selected - Competencies selected
16. worker_competencies_changed - Competencies updated
17. worker_under_supervision - Worker is being supervised
18. visitor_locked_on - Visitor locked on to site
19. worker_fatigue_check - Worker locked on for 10+ hrs
20. worker_fatigue_warning - Worker locked on for 11+ hrs
21. worker_fatigue_alert - Worker locked on for 12+ hrs
22. plant_qr_locked_on - Plant lock on
23. plant_qr_locked_off - Plant lock off
24. plant_manually_locked_on - Plant manual lock on
25. plant_manually_locked_off - Plant manual lock off
26. plant_operator_assigned - Operator assigned to Plant
27. plant_mpc_assigned - MPC assigned to Plant
28. plant_operator_reassigned - Plant Operator reassigned
29. plant_mpc_reassigned - Plant MPC reassigned
30. handover_initiated - Handover started
31. handover_completed - Handover succeeded
32. handover_cancelled - Handover failed/cancelled
33. pwa_handover_initiated - PWA Handover started
34. pwa_handover_completed - PWA Handover succeeded
35. pwa_handover_cancelled - Handover failed/cancelled
36. emergency_handover_initiated - Emergency handover started
37. emergency_handover_completed - Emergency handover successful
38. emergency_handover_cancelled - Emergency handover failed/cancelled
39. pwa_emergency_handover_initiated - PWA emergency handover started
40. pwa_emergency_handover_completed - PWA emergency handover successful
41. pwa_emergency_handover_cancelled - PWA emergency handover failed/cancelled
42. error_occurred - Any error encountered
43. offline_mode_entered - Device went offline
44. offline_mode_exited - Device back online

Track significant modal opens as virtual pageviews to enable funnel analysis. This allows us to create funnels like:

1. Worksite detail page
2. Lock-on worker modal
3. QR scan
4. Worker confirmation
5. Worker locked on

Performance Considerations

PostHog SDK adds approximately 50KB gzipped to bundle size. Lazy load PostHog if needed.

Non-blocking event capture:

• Events are captured asynchronously
• No impact on user interactions
• Failed captures fail silently

Offline Event Queuing

PostHog automatically queues events when offline. No additional configuration needed!

How it works:

1. Events captured while offline are stored in localStorage
2. When connection restored, queued events are sent automatically
3. Events include timestamp from when they occurred (not when synced)

Event Naming Conventions

Standard Format

Use snake_case for event names:

typescript

✅ 'worker_locked_on'
❌ 'WorkerLockedOn'
❌ 'worker-locked-on'

Use past tense verbs:

typescript

✅ 'modal_opened'
✅ 'handover_completed'
❌ 'open_modal'
❌ 'complete_handover'

Include entity type prefix where relevant:

typescript

✅ 'worker_locked_on'
✅ 'plant_locked_off'
✅ 'protection_activated'

Keep names concise but descriptive:

typescript

✅ 'handover_initiated'
❌ 'user_clicked_button_to_initiate_handover_process'

Property Naming

Use snake_case for property names:

typescript

{
  worksite_id: '123',
  user_role: 'Site Protector',
  duration_seconds: 45
}

Use consistent units:

typescript

✅ duration_seconds: 45
✅ duration_ms: 45000
❌ duration: 45 // What unit?

Include context properties:

typescript

{
  // Always include these where relevant
  worksite_id: worksiteId,
  pwa_id: pwaId,
  user_role: userRole,
  
  // Event-specific properties
  method: 'qr_code',
  worker_role: 'C'
}

Deployment Checklist

Pre-Production

• [ ] PostHog project created
• [ ] API key added to environment variables
• [ ] PostHog SDK installed and initialised
• [ ] User identification implemented (login/logout)
• [ ] Tier 1 critical events implemented
• [ ] Session recording privacy rules configured
• [ ] Testing in staging environment completed
• [ ] Event tracking validated in PostHog dashboard

Production Launch

• [ ] Production API key configured
• [ ] Debug mode disabled for production
• [ ] Session recording enabled
• [ ] Feature flags configured
• [ ] Team access to PostHog dashboard granted
• [ ] Initial dashboards created
• [ ] Documentation shared with team

Post-Launch (Week 1)

• [ ] Validate events are being captured
• [ ] Check event volume against free tier limits
• [ ] Adjust sampling rates if needed
• [ ] Create initial insights and funnels