add optional analytics using umami

hate · hate · commit 7018da1f8f0d · 2025-10-10T17:23:22.000-04:00
diff --git a/README.md b/README.md
@@ -37,7 +37,8 @@ Born from the need to master a new split keyboard layout while practicing real c
 - Real-time WPM, accuracy, and completion tracking
 - Per-session statistics with detailed breakdowns
 - Prompt-specific history to track improvement over time
-- All data stored locally in IndexedDB—nothing leaves your device
+- All personal data stored locally in IndexedDB—nothing leaves your device
+- Optional analytics (self-hosted, no personal data) - disabled by default
 
 **Built for Performance**
 - Rust WASM engine for blazing-fast diff calculation and scoring
@@ -118,7 +119,8 @@ pnpm build:web
 ## 🔒 Privacy First
 
 - **100% local** — All typing data, sessions, and progress stay on your device
-- **No analytics** — No tracking, cookies, or external requests
+- **Optional analytics** — Self-hosted analytics can be enabled to track aggregate usage (visits, runs started/completed)
+- **No personal data** — No cookies, no user identification, no external tracking services
 - **Offline-ready** — Works without an internet connection once loaded
 - **Open source** — Audit the code yourself
 
diff --git a/apps/web/index.html b/apps/web/index.html
@@ -8,6 +8,16 @@
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
   <link rel="apple-touch-icon" href="/favicon.svg" />
+  <script>
+    // Analytics will be loaded dynamically based on environment variables
+    if ( typeof __ANALYTICS_ENABLED__ !== 'undefined' && __ANALYTICS_ENABLED__ ) {
+      const script = document.createElement( 'script' );
+      script.async = true;
+      script.src = __ANALYTICS_URL__;
+      script.setAttribute( 'data-website-id', __ANALYTICS_WEBSITE_ID__ );
+      document.head.appendChild( script );
+    }
+  </script>
 </head>
 
 <body class="bg-slate-950 text-slate-100">
diff --git a/apps/web/src/features/session/hooks/usePersistCompletedSession.ts b/apps/web/src/features/session/hooks/usePersistCompletedSession.ts
@@ -72,6 +72,10 @@ export function usePersistCompletedSession({
         completedAt: finishedAtEpoch,
         attempts: attemptsSnapshot,
       });
+
+      if (typeof window !== "undefined" && window.umami) {
+        window.umami.track("run_completed");
+      }
       try {
         const event = new CustomEvent("devkeys:session-saved", {
           detail: {
diff --git a/apps/web/src/features/session/state/sessionStore.ts b/apps/web/src/features/session/state/sessionStore.ts
@@ -89,6 +89,10 @@ export const useSessionStore = create<SessionState>((set, get) => ({
     const nextStatus = reachedEnd ? "completed" : "active";
     const resolvedStatus = isEmpty ? "idle" : becameActive ? "active" : nextStatus;
 
+    if (becameActive && typeof window !== "undefined" && window.umami) {
+      window.umami.track("run_started");
+    }
+
     set({
       typed: trimmed,
       attempts,
diff --git a/apps/web/src/shared/types/umami.d.ts b/apps/web/src/shared/types/umami.d.ts
@@ -0,0 +1,5 @@
+interface Window {
+    umami?: {
+        track: (eventName: string, eventData?: Record<string, string | number>) => void;
+    };
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
@@ -3,4 +3,10 @@ import react from "@vitejs/plugin-react";
 
 export default defineConfig({
   plugins: [react()],
+  define: {
+    // Make environment variables available at build time
+    __ANALYTICS_URL__: JSON.stringify(process.env.VITE_ANALYTICS_URL || "https://analytics.website/script.js"),
+    __ANALYTICS_WEBSITE_ID__: JSON.stringify(process.env.VITE_ANALYTICS_WEBSITE_ID || "YOUR_WEBSITE_ID"),
+    __ANALYTICS_ENABLED__: JSON.stringify(process.env.VITE_ANALYTICS_ENABLED === "true"),
+  },
 });
diff --git a/docs/01_Overview_Principles.md b/docs/01_Overview_Principles.md
@@ -14,8 +14,8 @@
 **1. Code-native content**  
 Every prompt is real, idiomatic code—not random words or generic sentences. Practice algorithms, syntax patterns, and framework idioms that you'll actually use in your work.
 
-**2. True privacy**  
-All data stays on your device. Sessions, metrics, and custom prompts live in IndexedDB. No tracking, no analytics, no external API calls. Your typing data is yours alone.
+**2. Privacy-first design**  
+All personal data stays on your device. Sessions, metrics, and custom prompts live in IndexedDB. Optional anonymous analytics track only aggregate usage patterns (no personal data). Your typing data is yours alone.
 
 **3. Editor-like experience**  
 The UI borrows from modern IDEs: file-based prompt organization, language switching, syntax highlighting with VS Code themes, and Tab-aware indentation that respects code structure.
@@ -53,11 +53,12 @@ Generic typing trainers use news articles or literature. DevKeys uses code that
 
 ### 3. Own your data
 
-Privacy isn't a feature—it's the foundation. Sessions, progress, and custom prompts never leave your device. No servers, no sync, no cloud dependency.
+Privacy isn't a feature—it's the foundation. Sessions, progress, and custom prompts never leave your device. Optional anonymous analytics are self-hosted and track only aggregate usage.
 
 **In practice:**
 - IndexedDB for local persistence
-- No network requests after initial load
+- No personal data sent to external services
+- Anonymous analytics (if enabled) track only: page views, runs started, runs completed
 - Browser devtools provide full data access and export capability
 - Clear localStorage/IndexedDB to reset completely
 
@@ -94,13 +95,14 @@ The app works with the TypeScript evaluator out of the box. When the Rust WASM b
 
 ### 7. Offline matters
 
-Once the app loads, it should work indefinitely without network access. Prompts ship with the bundle. Metrics stay local. The only external dependency is the initial HTML/CSS/JS delivery.
+Once the app loads, it should work indefinitely without network access. Prompts ship with the bundle. Metrics stay local. Optional analytics are self-hosted and don't affect core functionality.
 
 **In practice:**
 - All prompt packs bundled at build time
 - No CDN dependencies for fonts or icons
 - IndexedDB persists across sessions
 - Static deployment (works on any file server)
+- Analytics (if enabled) are self-hosted and optional
 
 ---
 
@@ -180,7 +182,7 @@ DevKeys fails if:
 1. It requires cloud sync or accounts
 2. Keystroke latency becomes noticeable
 3. The bundle size grows beyond 500KB (gzipped)
-4. Privacy model changes to support growth
+4. Privacy model changes to collect personal data
 5. Core features require JavaScript frameworks beyond React
 
 ---
@@ -205,7 +207,7 @@ These are explicitly **not** goals for DevKeys:
 | Feature | DevKeys | Monkeytype | Typing.io | Keybr |
 |---------|---------|-----------|-----------|-------|
 | Code-first content | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
-| Privacy-first | ✅ Local only | ⚠️ Optional account | ❌ Account required | ⚠️ Analytics |
+| Privacy-first | ✅ Local + optional anonymous | ⚠️ Optional account | ❌ Account required | ⚠️ Analytics |
 | Custom prompts | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
 | Syntax highlighting | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
 | Open source | ✅ MIT | ✅ GPL-3.0 | ❌ No | ❌ No |
diff --git a/env.example b/env.example
@@ -0,0 +1,16 @@
+# DevKeys Environment Variables
+
+# =============================================================================
+# Analytics Configuration (Optional)
+# =============================================================================
+
+# Enable/disable analytics (default: false)
+# Set to 'true' to enable analytics, 'false' to disable
+VITE_ANALYTICS_ENABLED=false
+
+# Analytics script URL (update with your actual analytics domain)
+VITE_ANALYTICS_URL=https://website/script.js
+
+# Analytics website ID (get this from your Umami dashboard)
+VITE_ANALYTICS_WEBSITE_ID=your-website-id-here
+
diff --git a/umami-setup.md b/umami-setup.md
@@ -0,0 +1,89 @@
+# Optional Analytics Setup
+
+## Overview
+
+Analytics are **optional** and disabled by default. This guide shows how to enable self-hosted Umami analytics to track:
+
+1. Website visits (automatic pageviews)
+2. Run starts (custom event)
+3. Run completions (custom event)
+
+Umami is open source, privacy-first (no cookies), and you control all data on your own infrastructure.
+
+**Note**: The production example at `devkeys.app` has analytics enabled to demonstrate the feature. Your self-hosted instance will have analytics disabled by default.
+
+## Deployment Setup
+
+### 1. Deploy Umami
+
+Using your preferred container orchestration platform (Dokploy, Coolify, Docker Compose, etc.):
+
+1. **Create New Project** → **Docker Compose**
+2. Name it "umami-analytics"
+3. Paste this docker-compose configuration:
+
+```yaml
+services:
+  umami:
+    image: ghcr.io/umami-software/umami:postgresql-latest
+    environment:
+      DATABASE_URL: postgresql://umami:umami@db:5432/umami
+      DATABASE_TYPE: postgresql
+      APP_SECRET: ${APP_SECRET}
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: always
+    healthcheck:
+      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+  
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: umami
+      POSTGRES_USER: umami
+      POSTGRES_PASSWORD: umami
+    volumes:
+      - umami-db-data:/var/lib/postgresql/data
+    restart: always
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  umami-db-data:
+```
+
+4. **Set Environment Variables**:
+   - Copy `env.example` to `.env` and update the values
+   - `UMAMI_APP_SECRET` = generate random 32-char string
+   - `VITE_ANALYTICS_URL` = your analytics domain (e.g., `https://analytics.devkeys.app/script.js`)
+   - `VITE_ANALYTICS_WEBSITE_ID` = your website ID from Umami dashboard
+
+5. **Configure Domain**: Set up subdomain like `analytics.devkeys.app`
+6. **Enable HTTPS**: Most platforms auto-generate SSL via Let's Encrypt
+7. **Deploy** and wait for health checks to pass
+
+8. **Initial Setup**:
+   - Visit `https://analytics.devkeys.app`
+   - Default login: `admin` / `umami`
+   - Change password immediately
+   - Go to Settings → Websites → Add Website
+   - Enter your main site domain: `devkeys.app`
+   - Copy the **Website ID** from the tracking code
+
+### 2. Deploy Main App
+
+1. **Create New Project** → **Git Repository**
+2. Connect your GitHub repo
+3. Platform will auto-detect Vite/React
+4. **Build Settings**:
+   - Build Command: `pnpm install && pnpm build:wasm && pnpm build:web`
+   - Publish Directory: `apps/web/dist`
+5. Configure domain: `devkeys.app`
+6. Deploy
