Analytics Tracking Automation

# Analytics Tracking Automation

> Skill by [ara.so](https://ara.so) — Data Skills collection.

This skill enables AI agents to plan, implement, and deploy GA4 + GTM tracking setups. It automates site analysis, page grouping, event schema design, GTM container synchronization, preview verification, and publishing—supporting both generic websites and Shopify storefronts.

## What This Skill Does

The `analytics-tracking-automation` project provides a local-first workflow that:

1. **Analyzes** a website by crawling pages and identifying business intent
2. **Groups pages** by purpose (e.g., product, pricing, contact)
3. **Designs event schemas** (GA4 events, parameters, triggers) based on site structure
4. **Syncs to GTM** by creating/updating tags, triggers, variables via Google Tag Manager API
5. **Verifies in preview** using automated Playwright-based checks
6. **Publishes** the GTM container version when verification passes
7. **Supports Shopify** with specialized tracking for cart, checkout, and purchase flows
8. **Maintains artifacts** for resumable, reviewable tracking work

## Installation

### For Use in AI Agent Environments

The recommended installation is to clone the repository and install the skill bundle:

```bash
git clone https://github.com/jtrackingai/analytics-tracking-automation.git
cd analytics-tracking-automation
npm install
npm run install:skills
```

This installs the umbrella skill into your agent's skills directory and makes the `event-tracking` CLI available.

### No-Clone Alternative

```bash
npx skills add jtrackingai/analytics-tracking-automation
```

### Verify Installation

```bash
npx event-tracking --version
```

The CLI requires Node.js 18+ and will auto-install Playwright Chromium on first `npm install`.

## Core CLI Commands

The `event-tracking` CLI is the primary interface. All commands accept `--help` for detailed options.

### Start a New Tracking Setup

```bash
npx event-tracking init \
  --url https://www.example.com \
  --output ./output \
  --ga4-measurement-id G-XXXXXXXXXX
```

This creates a site artifact directory under `./output/` (e.g., `./output/www_example_com/`) and runs:
- Site crawl and page classification
- Business intent page grouping
- Event schema generation
- Schema review checkpoint

### Resume an Existing Run

```bash
npx event-tracking resume \
  --artifact-dir ./output/www_example_com \
  --continue-through sync
```

Resumes from the last checkpoint and continues through the specified stage (`schema`, `sync`, `preview`, `publish`).

### Audit an Existing GTM Setup

```bash
npx event-tracking audit \
  --url https://www.example.com \
  --gtm-account-id 123456789 \
  --gtm-container-id 12345678 \
  --output ./output
```

Compares live GTM configuration against recommended tracking plan and produces a health report.

### Sync Schema to GTM

```bash
npx event-tracking sync \
  --artifact-dir ./output/www_example_com \
  --gtm-account-id 123456789 \
  --gtm-container-id 12345678
```

Creates/updates tags, triggers, and variables in GTM based on `event-schema.json`. Requires Google OAuth (prompted interactively).

### Verify GTM Preview

```bash
npx event-tracking verify \
  --artifact-dir ./output/www_example_com \
  --gtm-preview-url "https://tagmanager.google.com/?gtm_preview=..."
```

Runs automated browser