olsch01
5a23f3d599
- Detect bot-like behavior (webdriver, missing language, etc.) - Track scroll depth (25%, 50%, 75%) - Track time on page (10+ seconds threshold) - Track all meaningful clicks - Add user properties (screen res, timezone, bot flag) - Filter real users from bots in GA4 reports - Add comprehensive documentation This enables: ✓ Distinguishing real users from automated traffic ✓ Measuring meaningful engagement vs vanity metrics ✓ Identifying calculator abandonment points ✓ Tracking user journey through the site ✓ Better ROI measurement for marketing efforts See GA4_ENHANCEMENTS.md for full details.
153 lines
4.4 KiB
Markdown
153 lines
4.4 KiB
Markdown
# 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
|