diff --git a/GA4_ENHANCEMENTS.md b/GA4_ENHANCEMENTS.md new file mode 100644 index 0000000..e58a5d8 --- /dev/null +++ b/GA4_ENHANCEMENTS.md @@ -0,0 +1,152 @@ +# GA4 Enhancements - Bot Detection & Engagement Tracking + +## Overview +This PR adds comprehensive GA4 event tracking with bot detection to distinguish real users from automated traffic and measure meaningful engagement. + +## What's Added + +### 1. ROI Calculator Tracking +- **`calculator_open`** - User opens the calculator modal +- **`calculator_submit`** - User submits the form (with anonymized homesites/reserve data) +- **`calculator_success`** - Results successfully displayed +- **`calculator_error`** - API or validation error occurred + +### 2. Bot Detection +Automatically flags likely bot traffic based on: +- `navigator.webdriver` detection (Selenium, Puppeteer, etc.) +- Missing language settings +- Invalid screen dimensions +- Automated browsing patterns + +**Custom Dimension:** `is_likely_bot` (true/false) + +### 3. Engagement Tracking +- **Scroll Depth:** 25%, 50%, 75% milestones +- **Time on Page:** Tracks if user stays 10+ seconds +- **Click Tracking:** All meaningful button/link clicks +- **Screen Resolution:** Captured as user property +- **Timezone:** Captured as user property + +## How to Identify Real Users in GA4 + +### Method 1: Filter by Bot Flag +``` +Filter: user_properties.is_likely_bot == 'false' +``` + +### Method 2: Engagement Thresholds +Real users typically: +- ✅ Scroll at least 25% of the page +- ✅ Stay on page 10+ seconds +- ✅ Click at least one element +- ✅ Have valid screen resolution +- ✅ Open calculator AND submit form + +### Method 3: Event Sequence +Real user pattern: +``` +page_view → scroll_25 → calculator_open → calculator_submit → calculator_success +``` + +Bot pattern: +``` +page_view → (no further events) OR page_view → calculator_submit (instant) +``` + +## GA4 Reports Location + +### Real-Time Testing +- **Reports** → Realtime → Event count +- Watch events as they happen +- Filter by `event_name` to see specific events + +### Historical Data +- **Reports** → Engagement → Events +- **Reports** → Engagement → Pages (filter by calculator page) +- **Explore** → Create custom exploration with: + - Dimensions: Event name, User properties, Engagement metrics + - Metrics: Event count, Total users, Engagement rate + +### Bot Filtering in GA4 +Create audience: +``` +Include: user_properties.is_likely_bot == 'false' +AND +Include: scroll_25 OR scroll_50 OR scroll_75 +AND +Include: time_on_page >= 10 +``` + +## Data Privacy +- ✅ No PII tracked (no email, name, IP addresses) +- ✅ Form values anonymized (only numeric ranges) +- ✅ Compliant with GA4 data retention policies +- ✅ Bot detection uses only browser-provided properties + +## Testing Instructions + +### 1. Verify Bot Detection +Open homepage and check browser console: +``` +✓ Enhanced GA4 tracking active +``` + +### 2. Test Calculator Events +1. Open calculator modal → Console: `✓ GA4: calculator_open event sent` +2. Submit form → Console: `✓ GA4: calculator_submit event sent` +3. View results → Console: `✓ GA4: calculator_success event sent` + +### 3. Test Engagement Tracking +1. Scroll page → Console: `✓ GA4: scroll_25/50/75 event sent` +2. Click buttons → Console: `✓ GA4: click event sent` +3. Wait 10+ seconds, then leave → Console: `✓ GA4: time_on_page event sent` + +### 4. Verify in GA4 +1. Go to GA4 → Realtime +2. You should see events appearing within 30 seconds +3. Check "User properties" for `is_likely_bot` dimension + +## Expected Results + +### Before Enhancement +- Total sessions: 146 (30 days) +- Bot vs Real: Unknown +- Calculator usage: Unknown +- Engagement: Unknown + +### After Enhancement +- Total sessions: [same] +- Bot sessions: Filtered out +- Real user sessions: Clear count +- Calculator opens: Exact count +- Calculator submissions: Exact count +- Submission rate: Calculated +- Engagement rate: Calculated + +## Troubleshooting + +### Events Not Appearing +1. Check browser console for errors +2. Verify GA4 property ID is correct (G-RTWNVXPMRF) +3. Check if ad blockers are blocking gtag +4. Wait up to 24 hours for data to appear in reports + +### Bot Detection False Positives +Some privacy-focused users may be flagged: +- Users with JavaScript disabled +- Users with Tor/VPN +- Users with unusual screen setups + +These can be filtered manually in GA4 explorations. + +## Future Enhancements +- [ ] Add conversion tracking (calculator → contact form) +- [ ] Track calculator abandonment rate +- [ ] Add funnel visualization in GA4 +- [ ] Create automated alerts for low engagement +- [ ] Integrate with CRM to track lead quality + +--- +**PR Branch:** feature/add-ga4-calculator-tracking +**Author:** AI Assistant +**Date:** 2026-03-29 diff --git a/index.html b/index.html index 963511d..edbd246 100644 --- a/index.html +++ b/index.html @@ -615,3 +615,82 @@ document.addEventListener('DOMContentLoaded', function() { + + +