diff --git a/agents/marketing-seo/GA4-INTEGRATION.md b/agents/marketing-seo/GA4-INTEGRATION.md new file mode 100644 index 0000000..6c3f71f --- /dev/null +++ b/agents/marketing-seo/GA4-INTEGRATION.md @@ -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`