HOALedgerIQ_Website/GA4_ENHANCEMENTS.md

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