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

GTM Audit Tool

Automated Google Tag Manager audit toolkit using Playwright browser automation.

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

Notion Integration

Export audit results directly to Notion database for tracking and collaboration.

# Export to default Notion database (OurDigital GTM Audit Log)
python gtm_audit.py --url "https://example.com" --notion

# Export with detailed content (issues, recommendations, checklist)
python gtm_audit.py --url "https://example.com" --notion --notion-detailed

# Export to custom Notion database
python gtm_audit.py --url "https://example.com" --notion --notion-database "your-database-id"

Notion Database Schema

Property	Type	Description
Site	Title	Domain name of audited site
Audit ID	Text	Unique identifier (GTM-domain-date-hash)
URL	URL	Full audited URL
Audit Date	Date	When audit was performed
Journey Type	Select	Audit journey type
GTM Status	Select	Installed / Not Found / Multiple Containers
Container IDs	Text	GTM container IDs found
Tags Fired	Multi-select	GA4, Google Ads, Meta Pixel, etc.
Issues Count	Number	Total issues found
Critical Issues	Number	Critical/error severity issues
Audit Status	Select	Pass / Warning / Fail
Summary	Text	Quick summary of findings

Environment Variables

Set NOTION_TOKEN or NOTION_API_KEY for Notion API authentication:

export NOTION_TOKEN="secret_xxxxx"

Default Database

Default Notion database: OurDigital GTM Audit Log

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