# 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`:
```python
GA_PROPERTY_ID = "526394825"  # Your GA4 Property ID
```

### Alert Thresholds
Edit in `scripts/seo-agent.py`:
```python
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
```bash
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
```bash
# Run one check
python3 scripts/seo-agent.py

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

### View Traffic History
```bash
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`