207 lines
4.5 KiB
Markdown
207 lines
4.5 KiB
Markdown
# 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`
|