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

cd ~/.openclaw/skills/ga-deep-dive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Get Google OAuth Credentials

Go to Google Cloud Console
Create a project (or use existing)
Enable Google Analytics Data API
Create OAuth 2.0 Client ID (Desktop app)
Download JSON → save as ~/.config/ga-deep-dive/credentials.json

3. Get Your GA4 Property ID

Open Google Analytics
Go to Admin → Property Settings
Copy the Property ID (9-digit number)

4. First Run (Auth)

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

# 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:

PROPERTIES = {
    'mysite': '123456789',
    'blog': '987654321',
}

Email Reports (Optional)

Configure via environment variables:

# Required for email functionality
export GA4_REPORT_RECIPIENTS="[email protected],[email protected]"
export AGENTMAIL_INBOX="[email protected]"
export AGENTMAIL_API_KEY="am_your_key_here"

Run with:

# 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:

# 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"

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 🏴‍☠️

Repository: https://github.com/fcavalcantirj/ga-deep-dive