Tracker Matomo Refactor

[bunsenstraat]

Refactor: Comprehensive Matomo Tracking System Overhaul

Overview

This PR introduces a new MatomoManager class that completely refactors Remix's analytics tracking system, providing better privacy controls, type safety, and developer experience.

🔧 Key Improvements

Privacy & Mode Management:

• ✅ Custom dimension tracking for anonymous vs cookie modes
• ✅ Click dimension tracking (dimension 3) for user interaction analytics
• ✅ Seamless mode switching without cookie persistence issues
• ✅ Proper initialization flow for new users requiring consent
• ✅ Pre-consent event queuing - events collected before user choice, sent after consent
• ✅ Enhanced anonymity with disableBrowserFeatureDetection in anonymous mode
• ✅ Bot detection system with 6-layer detection (user agent, automation flags, headless browsers, mouse behavior)
• ✅ Mouse movement analysis to distinguish human users from automation tools
• ✅ TrackingMode dimension set before bot detection event ensuring all events properly tagged

Custom Matomo Dimensions:

• 📊 Tracks user's consent state ('cookie', 'anon')
• 📊 click - Boolean flag indicating user-initiated click events
• 📊 'visitor bot detection' - Classification of detected bots ('automation', 'crawler', 'human', etc.)

Custom Matomo Bot Domain:

• Bot requests are sent ( optional ) to seperate domains on matomo

Code Architecture:

• ✅ Centralized tracking via MatomoManager and TrackingContext
• ✅ Type-safe event definitions in @remix-api
• ✅ Eliminated direct window._paq usage across entire codebase
• ✅ ESLint rules preventing direct _paq access
• ✅ Simplified settings tab using plugin calls

Developer Experience:

• ✅ Rich debugging methods exposed by MatomoManager
• ✅ Event-driven architecture for UI state management
• ✅ Comprehensive E2E tests for consent workflows
• ✅ Consistent tracking patterns across all plugins

Cleanup:

• ✅ Removed legacy loader.js
• ✅ Eliminated _paq.push() confusion
• ✅ Standardized all tracking calls

📋 Usage Examples

Type-Safe Event System

// Before: Manual _paq calls with no validation
_paq.push(['trackEvent', 'something', 'happened', 'maybe?'])

React Components (Context-based):

import { DebuggerEvents } from '@remix-api'
import { TrackingContext } from '@remix-ide/tracking'

const { trackMatomoEvent } = useContext(TrackingContext)
trackMatomoEvent?.(HomeTabEvents.featuredPluginsActionClick(pluginInfo.pluginTitle))
trackMatomoEvent?.(CompilerEvents.compiled('with_config_file_' + state.useFileConfiguration))
trackMatomoEvent?.(UdappEvents.safeSmartAccount('txExecuted', 'successfully'))

Plugin Classes (Direct calls):

import { trackMatomoEvent, BlockchainEvents, UdappEvents } from '@remix-api'

trackMatomoEvent(this, BlockchainEvents.deployWithProxy('modal ok confirmation'))
trackMatomoEvent(plugin, CompilerEvents.compiled(workspaceTemplateName))

🧪 Testing

• Added comprehensive E2E test suite covering consent flows, mode switching, and queue management
• Bot detection tests validating automation tool identification (35 assertions)
• Consent workflow tests covering 8 different user scenarios (200+ assertions)
• E2E state markers (matomo-bot-detection-complete, matomo-initialized, matomo-debug-plugin-loaded) eliminate flaky pause() calls
• All existing functionality preserved with improved reliability
• Tests pass consistently in both local and CI environments

📦 Core Files Added/Modified

New Matomo Core Files:

• apps/remix-ide/src/app/matomo/MatomoManager.ts - Main tracking manager with queue, consent, and mode switching
• apps/remix-ide/src/app/matomo/MatomoConfig.ts - Configuration and constants
• apps/remix-ide/src/app/matomo/MatomoAutoInit.ts - Automatic initialization logic
• apps/remix-ide/src/app/matomo/BotDetector.ts - Comprehensive bot detection with mouse behavior analysis
• apps/remix-ide/src/app/matomo/MatomoDebugPlugin.ts - E2E testing helper for event inspection
• apps/remix-ide/src/app/contexts/TrackingContext.tsx - React context provider for components
• libs/remix-ide/src/lib/tracking/TrackingFunction.ts - Factory for creating tracking functions

Type Definitions & Events:

• libs/remix-api/src/lib/plugins/matomo/core/base-types.ts - Core Matomo event types
• libs/remix-api/src/lib/plugins/matomo/events/*.ts - Type-safe event builders by category

Plugin Integration:

• apps/remix-ide/src/app/plugins/matomo.ts - Matomo plugin exposing tracking API

E2E Tests:

• apps/remix-ide-e2e/src/tests/matomo-consent*.test.ts - Comprehensive consent flow tests
• apps/remix-ide-e2e/src/tests/matomo-bot-detection.test.ts - Bot detection validation tests

Documentation:

• docs/matomo-bot-detection.md - Detailed bot detection mechanism documentation