diff --git a/.claude/commands/gtm-audit.md b/.claude/commands/gtm-audit.md index 4351d52..eb131e8 100644 --- a/.claude/commands/gtm-audit.md +++ b/.claude/commands/gtm-audit.md @@ -1,46 +1,68 @@ --- -description: Gtm Audit command +description: GTM page audit - scan fired tags, gap analysis, tag design from DOM, and report generation --- # GTM Audit -Lightweight Google Tag Manager audit tool. +Comprehensive Google Tag Manager audit using Playwright to scan live pages for container health, tag firing, dataLayer events, form tracking, and e-commerce checkout flows. ## Triggers -- "audit GTM", "check dataLayer", "GTM 검사" +- "audit GTM", "check dataLayer", "GTM 검사", "scan GTM tags", "audit tags on page", "check tag firing" ## Capabilities -1. **Container Analysis** - Tags, triggers, variables inventory -2. **DataLayer Validation** - Check event structure -3. **Form Tracking** - Verify form submission events -4. **E-commerce Check** - Validate purchase/cart events +1. **Container Analysis** — Verify GTM container loads, detect container ID, inventory tags/triggers/variables +2. **Tag Destination Detection** — Identify fired tags by network requests (GA4, Google Ads, Meta Pixel, LinkedIn, TikTok, Kakao, Naver, etc.) +3. **DataLayer Validation** — Check event structure, required fields, GA4 naming conventions +4. **Form Tracking** — Verify form submission events and field capture +5. **E-commerce Checkout Flow** — Validate purchase/cart/checkout events and required e-commerce parameters +6. **Journey-based Audit** — Target specific user journeys: `pageview`, `scroll`, `click`, `form`, `checkout`, `datalayer`, or `full` -## Scripts +## Script ```bash -# Audit GTM container -python /Users/ourdigital/Project/our-claude-skills/custom-skills/20-gtm-audit/code/scripts/gtm_audit.py \ - --url https://example.com +AUDIT_SCRIPT="/Users/ourdigital/Project/our-claude-skills/custom-skills/60-gtm-audit/code/scripts/gtm_audit.py" -# With detailed dataLayer check -python /Users/ourdigital/Project/our-claude-skills/custom-skills/20-gtm-audit/code/scripts/gtm_audit.py \ - --url https://example.com --check-datalayer --output report.json +# Basic page audit +python "$AUDIT_SCRIPT" --url "https://example.com" + +# Audit with expected container ID and specific journey +python "$AUDIT_SCRIPT" --url "https://example.com" --container GTM-XXXXXX --journey full + +# E-commerce checkout flow audit with JSON report +python "$AUDIT_SCRIPT" --url "https://example.com/checkout" --journey checkout --output report.json ``` +### Script Options +| Flag | Description | Default | +|------|-------------|---------| +| `--url` | Target URL to audit (required) | — | +| `--container` | Expected GTM container ID (e.g., GTM-XXXXXX) | auto-detect | +| `--journey` | Audit scope: `pageview`, `scroll`, `click`, `form`, `checkout`, `datalayer`, `full` | `pageview` | +| `--output` | Output file path for JSON report | `gtm_audit_report.json` | +| `--timeout` | Page load timeout in ms | `30000` | +| `--headless` | Run in headless mode | `True` | + ## Audit Checklist ### Container Health -- [ ] GTM container loads correctly -- [ ] No JavaScript errors from GTM -- [ ] Container ID matches expected +- [ ] GTM container loads without JavaScript errors +- [ ] Container ID matches expected value +- [ ] No duplicate container installations + +### Tag Firing & Destinations +- [ ] GA4 measurement requests detected +- [ ] Ad platform pixels fire correctly (Google Ads, Meta, etc.) +- [ ] No orphaned or misfiring tags ### DataLayer Events - [ ] `page_view` fires on all pages -- [ ] `purchase` event has required fields -- [ ] Form submissions tracked +- [ ] `purchase` event has required e-commerce fields +- [ ] Form submissions tracked with correct parameters +- [ ] Event names follow GA4 snake_case convention ### Common Issues -- Missing ecommerce object -- Incorrect event names (GA4 format) +- Missing or malformed ecommerce object +- Incorrect event names (not GA4 format) - Duplicate event firing +- Tags firing before dataLayer is ready diff --git a/.claude/commands/gtm-editor.md b/.claude/commands/gtm-editor.md index a096f09..0627797 100644 --- a/.claude/commands/gtm-editor.md +++ b/.claude/commands/gtm-editor.md @@ -6,6 +6,18 @@ description: GTM tag/trigger/variable creation via API with ES5 Custom HTML and Create, modify, and deploy GTM configurations via API. Generates ES5-compliant Custom HTML tags. +## Pre-Flight + +**BEFORE any API write operation**, read the relevant gotcha files at: +`~/Project/dintel-gtm-agent/docs/log/gotcha/` (see `README.md` for index) + +Priority reads per task: +- **Creating triggers** → `gotcha/triggers.md` (scrollDepth/timer limits, negate placement, naming) +- **Creating variables** → `gotcha/variables.md` (RegEx Table column names) +- **Writing regex conditions** → `gotcha/regex.md` (RE2 limitations) +- **Batch changes / publishing** → `gotcha/compilation.md` (workspace lifecycle) +- **Using DTM CLI** → `gotcha/dtm-cli.md` (commands that don't actually work) + ## Triggers - "create GTM tag", "generate dataLayer", "modify trigger" - "update variable", "write custom HTML", "manage GTM" diff --git a/.claude/commands/gtm-manager.md b/.claude/commands/gtm-manager.md deleted file mode 100644 index 720b8c7..0000000 --- a/.claude/commands/gtm-manager.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -description: Gtm Manager command ---- - -# GTM Manager - -Full GTM management with dataLayer injection and tag generation. - -## Triggers -- "GTM manager", "generate dataLayer tag", "dataLayer 태그 생성" - -## Capabilities - -1. **Full Audit** - Everything in gtm-audit plus more -2. **DataLayer Injector** - Generate custom HTML tags -3. **Event Mapping** - Map site actions to GA4 events -4. **Notion Export** - Save audit results to Notion - -## Scripts - -```bash -# Full GTM management -python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \ - --url https://example.com --full-audit - -# Generate dataLayer tag -python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \ - --generate-tag purchase --output purchase_tag.html - -# Export to Notion -python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \ - --url https://example.com --notion-export --database DATABASE_ID -``` - -## DataLayer Tag Templates - -### Purchase Event -```html - -``` - -## Environment -- `NOTION_TOKEN` - For Notion export (optional) diff --git a/.claude/commands/gtm-validator.md b/.claude/commands/gtm-validator.md index 7076f25..96ed072 100644 --- a/.claude/commands/gtm-validator.md +++ b/.claude/commands/gtm-validator.md @@ -6,6 +6,16 @@ description: GTM QA - tag firing verification, trigger testing, naming conventio Verify GTM implementations on live pages. Test triggers, validate dataLayer, check naming conventions. +## Pre-Flight + +**BEFORE starting validation**, read the relevant gotcha files at: +`~/Project/dintel-gtm-agent/docs/log/gotcha/` (see `README.md` for index) + +Priority reads per task: +- **Trigger validation** → `gotcha/triggers.md` + `gotcha/regex.md` +- **Post-API-change QA** → `gotcha/compilation.md` +- **Variable inspection** → `gotcha/variables.md` + ## Triggers - "validate tags", "QA GTM", "debug GTM" - "naming conventions", "GTM best practice" @@ -35,6 +45,59 @@ GTM snippet placement, dataLayer init, consent mode, ES5 compliance, sGTM endpoi ### 7. Version Comparison Compare tag counts and changes between container versions +## Gotchas (Hard-Won Lessons) + +### GTM Has Two Validation Layers — API CRUD vs Preview/Publish + +GTM API validates **schema only** during create/update calls (field names, types, required params). Regex patterns are stored as opaque strings and **never compiled** at edit time. Preview/Publish performs **full container compilation** — all regex is compiled by Google RE2, all variable references resolved, cross-resource dependencies checked. A resource can pass API validation but break Preview. + +**Rule**: After batch API changes, always attempt Preview before declaring success. + +### RE2 Does Not Support Lookaheads + +GTM's regex engine (RE2) is linear-time and deliberately omits: +- Negative lookahead `(?!...)` +- Positive lookahead `(?=...)` +- Lookbehind `(?<=...)` / `(?