Restore to commit 74e578279624c6045ca440a3459ebfa1f8d54191

UPGRADE_TRACKING_CHANGES.md

@@ -0,0 +1,87 @@
+# Upgrade Button & Popup Source Tracking
+
+## Summary
+Added an upgrade button to the apps page and implemented tracking for which popup source triggered upgrade page visits.
+
+## Changes Made
+
+### 1. Apps Page Upgrade Button
+**File**: `/chat/public/apps.html`
+- Added "Upgrade Plan" button in the action buttons area (alongside Upload ZIP, Create New App, Browse Templates)
+- Button links to `/upgrade?source=apps_page`
+- Styled with orange/amber gradient to stand out from other buttons
+
+### 2. Upgrade Page Source Tracking
+**File**: `/chat/public/upgrade.html`
+- Added JavaScript to read the `source` URL parameter when page loads
+- Created `trackUpgradePopupSource()` function to send tracking data to backend
+- Automatically tracks source when upgrade page is accessed
+
+### 3. Builder Page Tracking
+**Files**: `/chat/public/builder.html`, `/chat/public/builder.js`
+- Updated usage meter upgrade link to `/upgrade?source=usage_limit`
+- Added upgrade link to blurred model preview popup with `/upgrade?source=builder_model`
+- Link appears in the model selection dropdown when free users click the model selector
+
+### 4. Pricing Page Tracking
+**File**: `/chat/public/pricing.html`
+- Updated all upgrade buttons to include `?source=pricing` parameter
+- Covers Starter, Professional, and Enterprise plan buttons
+
+### 5. Server-Side Tracking Endpoint
+**File**: `/chat/server.js`
+- Created `handleUpgradePopupTracking(req, res)` function to process tracking requests
+- Added route: `POST /api/upgrade-popup-tracking`
+- Tracks normalized source values: `apps_page`, `builder_model`, `usage_limit`, `other`
+- Increments counters for each source in `trackingData.summary.upgradeSources`
+
+### 6. Server Stats API Update
+**File**: `/chat/server.js`
+- Updated `handleAdminTrackingStats()` to include `upgradeSources` in stats response
+- Data persisted to `.data/.opencode-chat/tracking.json`
+
+### 7. Admin Tracking UI
+**File**: `/chat/public/admin-tracking.html`
+- Added new "Upgrade Popup Sources" chart section
+- Created `renderUpgradeSourcesChart()` function
+- Displays bar chart showing which sources drive the most upgrade clicks
+- Updated `loadTrackingData()` to call new render function
+- Color-coded bars with orange/amber gradient (different from other charts)
+
+## Tracked Sources
+
+The system now tracks the following upgrade popup sources:
+
+1. **apps_page**: User clicked upgrade from the Apps page
+2. **builder_model**: User clicked upgrade from builder model selection (blurred preview)
+3. **usage_limit**: User clicked upgrade from usage meter/reached limit
+4. **other**: Any unknown source
+
+## Admin Dashboard
+
+Admin users can now see:
+- Total visits, unique visitors, referrers, pages
+- Signup and paid conversion sources
+- **Upgrade popup sources** (NEW)
+- Daily visits and revenue charts
+- Top referrers to upgrade page
+- Most visited pages
+- Retention metrics
+
+## Data Structure
+
+```javascript
+trackingData.summary.upgradeSources = {
+  apps_page: 0,
+  builder_model: 0,
+  usage_limit: 0,
+  other: 0
+}
+```
+
+## Benefits
+
+1. **User Journey Insights**: Understand which UI elements are driving upgrade interest
+2. **Feature Effectiveness**: Measure if model selection lockout is driving upgrades
+3. **UX Optimization**: Identify which CTAs are most effective
+4. **Conversion Funnel**: Track from popup view through to plan selection