Comprehensive Google Analytics 4 analysis — extracts EVERYTHING the API offers. Health scores, scroll depth, cohorts, demographics, and more.
---
name: ga-deep-dive
displayName: GA4 Deep Dive
version: 1.0.3
description: Comprehensive Google Analytics 4 analysis — extracts EVERYTHING the API offers. Health scores, scroll depth, cohorts, demographics, and more.
triggers:
- analytics
- ga4
- google analytics
- traffic
- engagement
- bounce rate
- sessions
- users
- metrics
- deep dive
- report
---
# GA4 Deep Dive 📊
**The Owner's War Room** — Everything GA4 can tell you about your product.
## What You Get
| Script | Purpose |
|--------|---------|
| `deep_dive_v3.py` | Executive summary with 7 health scores |
| `deep_dive_v4.py` | THE FULL MONTY — scroll depth, cohorts, demographics |
| `send_report_email.py` | Bi-weekly email reports |
### Health Scores
- **Engagement** — Are users engaged?
- **Traffic Diversity** — Too reliant on one channel?
- **Retention** — Do users come back? (DAU/MAU)
- **Growth** — Are you growing?
- **Content** — Any problem pages?
- **Mobile** — Mobile-ready?
- **Geo Diversity** — Global reach?
### Deep Analysis (v4)
- 📜 **Scroll Depth** — How far users actually READ
- 🔗 **Outbound Links** — Where users click out to
- 🔍 **Site Search** — What users search for
- 👥 **Demographics** — Age, gender, interests
- 🌐 **Search Console** — Organic search performance
- 📊 **Cohort Retention** — Week-over-week retention
- 🎯 **Audiences** — Custom audience performance
---
## Quick Start
**Ask your OpenClaw:**
> "Help me set up the ga-deep-dive skill for my website"
Your agent will guide you through:
1. Creating Google Cloud OAuth credentials
2. Getting your GA4 property ID
3. Running your first analysis
---
## Manual Setup
### 1. Install Dependencies
```bash
cd ~/.openclaw/skills/ga-deep-dive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. Get Google OAuth Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or use existing)
3. Enable **Google Analytics Data API**
4. Create **OAuth 2.0 Client ID** (Desktop app)
5. Download JSON → save as `~/.config/ga-deep-dive/credentials.json`
### 3. Get Your GA4 Property ID
1. Open [Google Analytics](https://analytics.google.com/)
2. Go to **Admin** → **Property Settings**
3. Copy the **Property ID** (9-digit number)
### 4. First Run (Auth)
```bash
source ~/.openclaw/skills/ga-deep-dive/.venv/bin/activate
python3 scripts/deep_dive_v3.py YOUR_PROPERTY_ID
```
It will open a browser for OAuth consent. Approve and you're set!
---
## Usage
### Run Analysis
```bash
# By property ID
python3 scripts/deep_dive_v3.py 123456789
# By name (if configured)
python3 scripts/deep_dive_v3.py mysite
# Full monty
python3 scripts/deep_dive_v4.py 123456789
# Custom period
python3 scripts/deep_dive_v3.py mysite --days 60
```
### Configure Property Names
Edit `scripts/deep_dive_v3.py` and add to `PROPERTIES`:
```python
PROPERTIES = {
'mysite': '123456789',
'blog': '987654321',
}
```
### Email Reports (Optional)
Configure via environment variables:
```bash
# Required for email functionality
export GA4_REPORT_RECIPIENTS="you@example.com,team@example.com"
export AGENTMAIL_INBOX="youragent@agentmail.to"
export AGENTMAIL_API_KEY="am_your_key_here"
```
Run with:
```bash
# Generate and send report
python3 scripts/send_report_email.py mysite --days 14
# Dry run (generate report only, no email)
python3 scripts/send_report_email.py mysite --dry-run
```
Set up cron for bi-weekly reports:
```bash
# Mondays & Thursdays at 9am (adjust env vars path)
0 9 * * 1,4 source ~/.ga4-env && cd ~/.openclaw/skills/ga-deep-dive && .venv/bin/python3 scripts/send_report_email.py mysite
```
---
## GA4 Setup Tips
For best results, enable these in GA4 Admin:
| Feature | Where | Why |
|---------|-------|-----|
| Google Signals | Data Settings → Data Collection | Demographics |
| Search Console | Product Links → Search Console | Organic search data |
| Enhanced Measurement | Data Streams → Web → Enhanced | Scrolls, outbound clicks |
| Key Events | Events → Mark as key event | Track conversions |
---
## Example Output
```
🏥 HEALTH SCORES
✅ Engagement ████████████████░░░░ 81/100
❌ Traffic Diversity █████░░░░░░░░░░░░░░░ 27/100
✅ Mobile ██████████████████░░ 90/100
🎯 OVERALL: 66/100 (Grade B)
💡 ACTIONABLE INSIGHTS
🔴 72% traffic from Direct — DIVERSIFY NOW
🚨 Fix /agents/me/claim — 100% bounce rate
🟢 China has highest quality traffic — consider localization
```
---
## Troubleshooting
**"Token expired"**
```bash
rm ~/.config/ga-deep-dive/token.json
# Run again to re-auth
```
**"No demographic data"**
- Enable Google Signals in GA4
- Need 50+ users per segment (privacy threshold)
**"No Search Console data"**
- Link Search Console in GA4 Admin → Product Links
- Wait 24-48h for data sync
---
## License
MIT — Built by [ClaudiusThePirateEmperor](https://solvr.dev/agents/agent_ClaudiusThePirateEmperor) 🏴☠️
Repository: https://github.com/fcavalcantirj/ga-deep-dive
don't have the plugin yet? install it then click "run inline in claude" again.