JoeBot/HOALedgerIQ_Website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e59ddd045d099d1f6bebd642cca470325de10e26
HOALedgerIQ_Website/agents/marketing-seo/GA4-INTEGRATION.md

4.5 KiB
Raw Blame History

GA4 Analytics Integration - SEO Agent

Overview

The SEO Agent now integrates with Google Analytics 4 to provide real-time traffic monitoring and anomaly detection as part of your morning brief.

Implemented: April 1, 2026

What's New

1. GA4 Data Collection

The SEO agent now fetches:

  • Sessions - Total visits in the last 24 hours
  • Active Users - Unique users in the last 24 hours
  • Bounce Rate - Percentage of single-page visits
  • New Users - First-time visitors

2. Traffic Anomaly Detection

Automatically alerts when:

  • Traffic drops >50% compared to 7-day average
  • Significant session declines detected
  • Unusual bounce rate patterns

3. Historical Tracking

  • Maintains 30-day traffic history in state
  • Compares current data against rolling averages
  • Stores timestamps for trend analysis

4. Morning Brief Integration

GA4 data now appears in your daily 8 AM report:

📊 DAILY SEO REPORT - Wed Apr 01

🌐 Sites:
✅ www.hoaledgeriq.com: 200
✅ app.hoaledgeriq.com: 200

📈 Traffic (24h):
• Sessions: 2
• Users: 2
• Bounce Rate: 45.2%

📈 Rankings:
• Tracking 8 keywords
• Monitoring for breakthrough

⚡ Status: Healthy ✅

How It Works

Data Flow

  1. Hourly Check (every 6 hours to avoid API fatigue)

    • SEO agent calls ga4-direct.py
    • Fetches last 24h traffic data from GA4
    • Compares against historical averages
    • Triggers alert if anomaly detected

  2. Daily Report (8:00 AM)

    • Comprehensive traffic summary
    • Site health status
    • Rankings update
    • Sent to Telegram

  3. State Management

    • Traffic data stored in state/agent-state.json
    • 30-day rolling history
    • Survives restarts

Files Modified

  • scripts/seo-agent.py - Main agent with GA4 integration
  • scripts/daily-report.sh - Enhanced morning brief
  • scripts/ga4-direct.py - GA4 API connector (already existed)
  • scripts/ga4-monitor.py - GA4 helper functions (already existed)

Configuration

GA4 Property ID

Located in scripts/ga4-monitor.py:

GA_PROPERTY_ID = "526394825"  # Your GA4 Property ID

Alert Thresholds

Edit in scripts/seo-agent.py:

TRAFFIC_DROP_THRESHOLD = 0.50  # Alert if traffic drops >50%

Check Frequency

  • Site health: Every hour
  • GA4 traffic: Every 6 hours (to avoid API fatigue)
  • Daily report: 8:00 AM sharp

Testing

Test GA4 Connection

cd /Users/claw/.openclaw/workspace/agents/marketing-seo
python3 scripts/ga4-direct.py

Expected output:

🚀 Testing GA4 Direct Connection...
📊 GA4 Traffic Data (Last 24h):
✅ Sessions: 2
✅ Active Users: 2
✅ New Users: 2

Test SEO Agent

# Run one check
python3 scripts/seo-agent.py

# Or check logs
tail -f logs/seo-agent-20260401.log

View Traffic History

cat state/agent-state.json | jq .traffic_history

Alerts

You'll receive Telegram notifications for:

  1. Traffic Drops (>50% below average)

    🔔 SEO Alert: Traffic Anomaly Detected

🚨 Traffic drop detected: 52.3% below average
• Current: 1 sessions
• 7-day avg: 2 sessions
• Threshold: 50% drop

  2. Site Downtime

    🔔 SEO Alert: SITE DOWN

Status: Connection refused
URL: https://www.hoaledgeriq.com

  3. Daily Summary (8 AM)

    • Complete traffic overview
    • Site health status
    • Rankings update

Troubleshooting

GA4 Data Not Appearing

  1. Check credentials: config/ga-credentials.json
  2. Verify property ID in ga4-monitor.py
  3. Test connection: python3 scripts/ga4-direct.py

Alerts Not Sending

  1. Verify Telegram bot is configured
  2. Check openclaw message command works
  3. Review logs: logs/alerts-20260401.log

High API Usage

If you hit GA4 API limits:

  • Increase MONITOR_INTERVAL in seo-agent.py
  • Reduce GA4 check frequency (currently every 6h)
  • Use cached data from state file

Next Steps

Recommended Enhancements

  • Add Search Console integration (impressions, clicks, CTR)
  • Track top pages/landing pages
  • Add conversion tracking
  • Create weekly/monthly trend reports
  • Integrate with rank tracking for correlation analysis

Optional Features

  • Email reports (in addition to Telegram)
  • Slack webhook support
  • Custom date range queries
  • Real-time dashboard (Grafana/DataDog)

Support

Maintained by: Forge (Chris's SaaS Operations Bot)
GA4 Property: 526394825 (HOA Ledger IQ)
Documentation: /Users/claw/.openclaw/workspace/agents/marketing-seo/GA4-INTEGRATION.md