# 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