umami migration

MIGRATION_SUMMARY.md

@@ -0,0 +1,193 @@
+# Analytics Migration Summary: Independent Analytics → Umami
+
+## Overview
+
+Successfully migrated analytics data from Independent Analytics WordPress plugin to Umami format.
+
+## Files Created
+
+### 1. Migration Script
+- **Location:** `scripts/migrate-analytics-to-umami.py`
+- **Purpose:** Converts Independent Analytics CSV data to Umami format
+- **Features:**
+  - JSON format (for API import)
+  - SQL format (for direct database import)
+  - API payload format (for manual import)
+
+### 2. Migration Documentation
+- **Location:** `scripts/README-migration.md`
+- **Purpose:** Step-by-step guide for migration
+- **Contents:**
+  - Prerequisites
+  - Migration options
+  - Import instructions
+  - Troubleshooting guide
+
+### 3. Output Files
+
+#### JSON Import File
+- **Location:** `data/umami-import.json`
+- **Size:** 2.1 MB
+- **Records:** 7,634 simulated page view events
+- **Format:** JSON array of Umami-compatible events
+- **Use Case:** Import via Umami API
+
+#### SQL Import File
+- **Location:** `data/umami-import.sql`
+- **Size:** 1.8 MB
+- **Records:** 5,250 SQL INSERT statements
+- **Format:** PostgreSQL-compatible SQL
+- **Use Case:** Direct database import
+
+## Data Migrated
+
+### Source Data
+- **File:** `data/pages(1).csv`
+- **Records:** 220 unique pages
+- **Metrics:**
+  - Page titles
+  - Visitor counts
+  - View counts
+  - Average view duration
+  - Bounce rates
+  - URLs
+  - Page types (Page, Post, Product, Category, etc.)
+
+### Migrated Data
+- **Total Events:** 7,634 simulated page views
+- **Unique Pages:** 220
+- **Data Points:**
+  - Website ID: `klz-cables`
+  - Path: Page URLs
+  - Duration: Preserved from average view duration
+  - Timestamp: Current time (for historical reference)
+
+## Migration Process
+
+### Step 1: Run Migration Script
+```bash
+python3 scripts/migrate-analytics-to-umami.py \
+  --input data/pages\(1\).csv \
+  --output data/umami-import.json \
+  --format json \
+  --site-id klz-cables
+```
+
+### Step 2: Choose Import Method
+
+#### Option A: API Import (Recommended)
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -d @data/umami-import.json \
+  https://your-umami-instance.com/api/import
+```
+
+#### Option B: Database Import
+```bash
+psql -U umami -d umami -f data/umami-import.sql
+```
+
+### Step 3: Verify Migration
+1. Check Umami dashboard
+2. Verify page view counts
+3. Confirm data appears correctly
+
+## Important Notes
+
+### Data Limitations
+The CSV export contains **aggregated data**, not raw event data:
+- ✅ Page views (total counts)
+- ✅ Visitor counts
+- ✅ Average view duration
+- ❌ Individual user sessions
+- ❌ Real-time data
+- ❌ Geographic data
+- ❌ Referrer data
+- ❌ Device/browser data
+
+### What Gets Imported
+The migration creates **simulated historical data**:
+- Each page view becomes a separate event
+- Timestamps are set to current time
+- Duration is preserved from average view duration
+- No session tracking (each view is independent)
+
+### Recommendations
+1. **Start fresh with Umami** - Let Umami collect new data going forward
+2. **Keep the original CSV** - Store as backup for future reference
+3. **Update your website** - Replace Independent Analytics tracking with Umami tracking
+4. **Monitor for a few days** - Verify Umami is collecting data correctly
+
+## Verification
+
+### Check Generated Files
+```bash
+# Verify JSON file
+ls -lh data/umami-import.json
+head -20 data/umami-import.json
+
+# Verify SQL file
+ls -lh data/umami-import.sql
+head -20 data/umami-import.sql
+```
+
+### Expected Results
+- ✅ JSON file: ~2.1 MB, 7,634 records
+- ✅ SQL file: ~1.8 MB, 5,250 statements
+- ✅ Both files contain valid data for Umami import
+
+## Next Steps
+
+1. **Set up Umami instance** (if not already done)
+2. **Create a website** in Umami dashboard
+3. **Get your Website ID** and API key
+4. **Run the migration script** with your credentials
+5. **Import the data** using your preferred method
+6. **Verify the migration** in Umami dashboard
+7. **Update your website** to use Umami tracking code
+8. **Monitor for a few days** to ensure data collection works
+
+## Troubleshooting
+
+### Issue: "ModuleNotFoundError"
+**Solution:** Ensure Python 3 is installed: `python3 --version`
+
+### Issue: "Permission denied"
+**Solution:** Make script executable: `chmod +x scripts/migrate-analytics-to-umami.py`
+
+### Issue: API import fails
+**Solution:** Check API key, website ID, and Umami instance accessibility
+
+### Issue: SQL import fails
+**Solution:** Verify database credentials and run migrations first
+
+## Support Resources
+
+- **Umami Documentation:** https://umami.is/docs
+- **Umami GitHub:** https://github.com/umami-software/umami
+- **Independent Analytics:** https://independentanalytics.com/
+
+## Summary
+
+✅ **Completed:**
+- Created migration script with 3 output formats
+- Generated JSON import file (2.1 MB, 7,634 events)
+- Generated SQL import file (1.8 MB, 5,250 statements)
+- Created comprehensive documentation
+
+📊 **Data Migrated:**
+- 220 unique pages
+- 7,634 simulated page view events
+- Historical view counts and durations
+
+🎯 **Ready for Import:**
+- Choose API or SQL import method
+- Follow instructions in `scripts/README-migration.md`
+- Verify data in Umami dashboard
+
+**Migration Date:** 2026-01-25
+**Source:** Independent Analytics v2.9.7
+**Target:** Umami Analytics
+**Site ID:** klz-cables