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 checks against GTM preview mode, validates event firing, and produces a verification report. ### Publish GTM Container ```bash npx event-tracking publish \ --artifact-dir ./output/www_example_com \ --gtm-account-id 123456789 \ --gtm-container-id 12345678 \ --version-name "v1.0 - Initial tracking" ``` Publishes the current workspace version to live. ### Shopify-Specific Setup ```bash npx event-tracking init \ --url https://store.example.com \ --output ./output \ --platform shopify \ --ga4-measurement-id G-XXXXXXXXXX ``` Uses Shopify-optimized tracking (cart, checkout, purchase events). ## Configuration ### Environment Variables ```bash # Google OAuth credentials (create in Google Cloud Console) export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com export GOOGLE_CLIENT_SECRET=your-client-secret # Optional: GA4 Measurement ID export GA4_MEASUREMENT_ID=G-XXXXXXXXXX # Optional: GTM Account/Container IDs export GTM_ACCOUNT_ID=123456789 export GTM_CONTAINER_ID=12345678 ``` ### OAuth Setup To sync with GTM, you need Google OAuth credentials: 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a project and enable Tag Manager API 3. Create OAuth 2.0 credentials (Desktop app type) 4. Set redirect URI to `http://localhost:3000/oauth/callback` 5. Export `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` First sync will open a browser for OAuth consent. Credentials are cached in the artifact directory (`oauth-tokens.json`). ## Artifact Directory Structure Each site run creates an artifact directory like `./output/www_example_com/`: ``` www_example_com/ ├── site-analysis.json # Crawl results, page inventory ├── page-groups.json # Business intent groupings ├── event-schema.json # GA4 events, parameters, triggers ├── gtm-sync-result.json # GTM API operation results ├── verification-report.json # Preview verification checks ├── oauth-tokens.json # Cached OAuth credentials └── checkpoint.json # Last completed stage ``` These files are reviewable, editable, and resumable. ## TypeScript API Examples ### Programmatic Site Analysis ```typescript import { analyzeSite } from 'analytics-tracking-automation'; async function analyzeSiteExample() { const result = await analyzeSite({ url: 'https://www.example.com', outputDir: './output', maxPages: 100, includeSubdomains: false, }); console.log('Pages discovered:', result.pages.length); console.log('Page groups:', result.pageGroups); console.log('Recommended events:', result.events.length); } ``` ### Generate Event Schema ```typescript import { generateEventSchema } from 'analytics-tracking-automation'; async function generateSchemaExample() { const schema = await generateEventSchema({ artifactDir: './output/www_example_com', pageGroups: ['home', 'product', 'pricing', 'contact'], businessGoals: ['signup', 'purchase', 'demo_request'], }); console.log('Generated events:', schema.events); console.log('Event parameters:', schema.parameters); console.log('GTM triggers:', schema.triggers); } ``` ### Sync to GTM ```typescript import { syncToGTM } from 'analytics-tracking-automation'; async function syncExample() { const syncResult = await syncToGTM({ artifactDir: './output/www_example_com', gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); console.log('Tags created:', syncResult.tagsCreated); console.log('Triggers created:', syncResult.triggersCreated); console.log('Variables created:', syncResult.variablesCreated); } ``` ### Verify Preview ```typescript import { verifyPreview } from 'analytics-tracking-automation'; async function verifyExample() { const report = await verifyPreview({ artifactDir: './output/www_example_com', gtmPreviewUrl: 'https://tagmanager.google.com/?gtm_preview=...', testPages: [ { url: 'https://www.example.com/', expectedEvents: ['page_view'] }, { url: 'https://www.example.com/pricing', expectedEvents: ['page_view', 'view_pricing'] }, { url: 'https://www.example.com/contact', expectedEvents: ['page_view', 'contact_intent'] }, ], }); console.log('Checks passed:', report.passed); console.log('Checks failed:', report.failed); console.log('Issues:', report.issues); } ``` ### Publish Container ```typescript import { publishContainer } from 'analytics-tracking-automation'; async function publishExample() { const result = await publishContainer({ gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, versionName: 'v1.0 - Initial tracking setup', versionDescription: 'GA4 events for core user journeys', oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); console.log('Published version:', result.publishedVersion); console.log('Live container URL:', result.containerUrl); } ``` ## Common Patterns ### Full End-to-End Setup ```typescript import { analyzeSite, generateEventSchema, syncToGTM, verifyPreview, publishContainer, } from 'analytics-tracking-automation'; async function fullSetup(url: string, outputRoot: string) { // 1. Analyze site const analysis = await analyzeSite({ url, outputDir: outputRoot }); const artifactDir = analysis.artifactDir; // 2. Generate schema const schema = await generateEventSchema({ artifactDir }); // 3. Review (manual checkpoint) console.log('Review schema before syncing:', schema); // User reviews and edits event-schema.json if needed // 4. Sync to GTM const syncResult = await syncToGTM({ artifactDir, gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); // 5. Enter GTM preview mode manually, then verify const previewUrl = '...'; // GTM preview URL from user const verifyReport = await verifyPreview({ artifactDir, gtmPreviewUrl: previewUrl }); if (verifyReport.passed === verifyReport.total) { // 6. Publish await publishContainer({ gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, versionName: 'v1.0 - Automated setup', oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); console.log('Published successfully'); } else { console.error('Verification failed, fix issues before publishing'); } } ``` ### Shopify Tracking Setup ```typescript import { analyzeSite, generateEventSchema, syncToGTM } from 'analytics-tracking-automation'; async function shopifySetup(storeUrl: string) { const analysis = await analyzeSite({ url: storeUrl, outputDir: './output', platform: 'shopify', }); const schema = await generateEventSchema({ artifactDir: analysis.artifactDir, platform: 'shopify', shopifyEvents: ['add_to_cart', 'begin_checkout', 'purchase'], }); await syncToGTM({ artifactDir: analysis.artifactDir, gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, platform: 'shopify', oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); console.log('Shopify tracking synced. Manual verification required in Shopify admin.'); } ``` ### Audit Existing Setup ```typescript import { auditGTM } from 'analytics-tracking-automation'; async function auditExample(url: string) { const auditReport = await auditGTM({ url, gtmAccountId: process.env.GTM_ACCOUNT_ID!, gtmContainerId: process.env.GTM_CONTAINER_ID!, outputDir: './output', oauthCredentials: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }, }); console.log('Healthy tags:', auditReport.healthy); console.log('Drifted tags:', auditReport.drifted); console.log('Missing events:', auditReport.missing); console.log('Recommendations:', auditReport.recommendations); } ``` ### Resume from Checkpoint ```typescript import { resumeWorkflow } from 'analytics-tracking-automation'; async function resumeExample(artifactDir: string) { const result = await resumeWorkflow({ artifactDir, continueThrough: 'publish', // 'schema' | 'sync' | 'preview' | 'publish' }); console.log('Resumed from:', result.lastCheckpoint); console.log('Completed through:', result.completedStage); } ``` ## Debugging and Troubleshooting ### Selector Debugging with Playwright If preview verification reports selector mismatches or events not firing: ```bash # Open site in headed browser for visual inspection