shopify-ai-backup/UPGRADE_TRACKING_CHANGES.md

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

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