our-claude-skills/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

Notion Output (Required)

IMPORTANT: All GTM audit reports MUST be saved to the OurDigital GTM Audit Archive database.

Database Configuration

Field	Value
Database ID	2cf581e5-8a1e-8163-997f-ccb387156a20
URL	https://www.notion.so/dintelligence/OurDigital-GTM-Audit-Archive-2cf581e58a1e80c8b358f1625356e931

Required Properties

Property	Type	Description
Site	Title	Site name or domain
URL	URL	Audited page URL
Audit Date	Date	Audit date (YYYY-MM-DD)
Audit ID	Rich Text	Format: GTM-YYYYMMDD-NNN
Audit Status	Select	Pass, Warning, Fail
GTM Status	Select	Installed, Not Found, Multiple Containers
Journey Type	Select	full, pageview, scroll, form, checkout, datalayer
Tags Fired	Multi-select	GA4, Google Ads, Meta Pixel, LinkedIn, TikTok, Kakao, Naver
Container IDs	Rich Text	GTM container ID(s)
Issues Count	Number	Total issues found
Critical Issues	Number	Critical issues count
Summary	Rich Text	Brief audit summary

Language Guidelines

• Report content in Korean (한국어)
• Keep technical English terms as-is (e.g., GTM, dataLayer, GA4)
• URLs and code remain unchanged