ga-deep-dive

# 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/a...

# GA4 Deep Dive 🏴‍☠️

Comprehensive Google Analytics 4 property analysis — extracts EVERYTHING the API offers.

Built by Claudius for Solvr.

## Features

### Scripts

| Script | Purpose |
|--------|---------|
| `deep_dive_v3.py` | Executive summary with health scores |
| `deep_dive_v4.py` | THE FULL MONTY — everything GA4 can tell you |
| `send_report_email.py` | Email reports via AgentMail |
| `weekly_report.py` | Weekly comparison reports |

### V3 — Executive Summary
- Period comparison (this vs last)
- Health scores (7 dimensions)
- Traffic source analysis
- Content performance
- User segments
- Time patterns

### V4 — The Full Monty
- Scroll depth analysis
- Outbound link tracking
- Site search analysis
- Demographics (with Google Signals)
- Search Console integration
- Cohort retention
- Custom audience performance
- Event deep dive
- Mobile device breakdown

## Setup

```bash
cd ~/development/ga-deep-dive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Auth (first time)

1. Create OAuth credentials in Google Cloud Console
2. Place `credentials.json` at `~/.config/ga-deep-dive/credentials.json`
3. Run any script — it will prompt for auth

## Usage

```bash
# Quick executive summary
python3 scripts/deep_dive_v3.py solvr

# Full analysis
python3 scripts/deep_dive_v4.py solvr --days 30

# Email report
python3 scripts/send_report_email.py
```

## Cron Setup

Bi-weekly reports (Mon & Thu at 9am São Paulo):
```bash
0 12 * * 1,4 cd ~/development/ga-deep-dive && .venv/bin/python3 scripts/send_report_email.py >> data/cron.log 2>&1
```

## Properties

| Name | Property ID |
|------|-------------|
| solvr | 523300499 |
| abecmed | 291040306 |
| sonus | 517562144 |

---
*Built for owners who want to UNDERSTAND their product, not just see numbers.* 🏴‍☠️