docs: Add GA4 integration documentation
This commit is contained in:
206
agents/marketing-seo/GA4-INTEGRATION.md
Normal file
206
agents/marketing-seo/GA4-INTEGRATION.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user