our-claude-skills/ourdigital-custom-skills/20-gtm-audit/code/CLAUDE.md

OurDigital GTM Audit

Lightweight Google Tag Manager audit toolkit using Playwright browser automation.

For comprehensive GTM management including dataLayer tag generation, see 14-ourdigital-gtm-manager.

Project Overview

This tool audits GTM container installations, validates dataLayer events, tests form tracking, simulates e-commerce checkout flows, and generates comprehensive reports.

Quick Commands

# Install dependencies
pip install playwright
playwright install chromium

# Run full audit
python gtm_audit.py --url "https://example.com" --journey full

# Form tracking audit
python gtm_audit.py --url "https://example.com/contact" --journey form

# E-commerce checkout flow
python gtm_audit.py --url "https://example.com/cart" --journey checkout

# DataLayer deep inspection
python gtm_audit.py --url "https://example.com" --journey datalayer

# With specific container validation
python gtm_audit.py --url "https://example.com" --container "GTM-XXXXXX"

Journey Types

Journey	Description
pageview	Basic page load + scroll simulation
scroll	Scroll depth trigger testing (25%, 50%, 75%, 90%)
form	Form discovery, field analysis, interaction simulation
checkout	E-commerce flow: cart → checkout → shipping → payment → purchase
datalayer	Deep dataLayer validation and event sequence analysis
full	All of the above combined

Output

Generates gtm_audit_report.json with:

• Container status (installed, position, duplicates)
• DataLayer analysis (events, validation issues, sequence errors)
• Form analysis (forms found, tracking readiness, missing events)
• Checkout analysis (elements detected, flow issues)
• Network requests (GA4, Meta, LinkedIn, etc.)
• Recommendations and checklist

Key Files

• gtm_audit.py - Main audit script
• docs/ga4_events.md - GA4 event specifications
• docs/ecommerce_schema.md - E-commerce dataLayer structures
• docs/form_tracking.md - Form event patterns
• docs/checkout_flow.md - Checkout funnel sequence
• docs/datalayer_validation.md - Validation rules
• docs/common_issues.md - Frequent problems and fixes

Coding Guidelines

When modifying this tool:

1. Tag Destinations: Add new platforms to TAG_DESTINATIONS dict
2. Event Validation: Add requirements to GA4_EVENT_REQUIREMENTS dict
3. Form Selectors: Extend FormAnalyzer.discover_forms() for custom forms
4. Checkout Elements: Add selectors to CheckoutFlowAnalyzer.detect_checkout_elements()

Korean Market Considerations

• Support Korean payment methods (카카오페이, 네이버페이, 토스)
• Handle KRW currency (no decimals)
• Include Kakao Pixel and Naver Analytics patterns
• Korean button text patterns (장바구니, 결제하기, 주문하기)

Testing a New Site

1. Run with --journey full first to get complete picture
2. Check gtm_audit_report.json for issues
3. Focus on specific areas with targeted journey types
4. Use --container GTM-XXXXXX to validate specific container

Common Tasks

Add support for new tag platform

# In TAG_DESTINATIONS dict
"NewPlatform": [
    r"tracking\.newplatform\.com",
    r"pixel\.newplatform\.com",
],

Add custom form field detection

# In FormAnalyzer.discover_forms()
# Add new field types or selectors

Extend checkout flow for specific platform

# In CheckoutFlowAnalyzer.detect_checkout_elements()
# Add platform-specific selectors