our-claude-skills/ourdigital-custom-skills/21-gtm-manager/code/CLAUDE.md

OurDigital GTM Manager

Comprehensive Google Tag Manager management toolkit - audit, analyze, and generate dataLayer implementations.

Note

: For lightweight audit-only functionality, see 13-ourdigital-gtm-audit.

Project Overview

This tool provides two main capabilities:

1. Audit: Validate GTM installations, analyze dataLayer events, test form/checkout tracking
2. Inject: Generate custom HTML tags for dataLayer pushes when direct code access is unavailable

Quick Commands

# Install dependencies
pip install playwright
playwright install chromium

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

# Audit with Notion export
python gtm_manager.py audit --url "https://example.com" --notion

# Audit and generate missing tags
python gtm_manager.py audit --url "https://example.com" --generate-tags

# INJECT MODE
# List available event types
python gtm_manager.py inject --list-events

# Generate all ecommerce tags
python gtm_manager.py inject --preset ecommerce --output ./tags

# Generate specific event tags
python gtm_manager.py inject --event purchase --event add_to_cart

# Generate from audit report
python gtm_manager.py inject --from-audit gtm_audit_report.json

# Generate with DOM scraping
python gtm_manager.py inject --event view_item --scrape

Audit Mode

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

Audit 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

Inject Mode

Generate GTM custom HTML tags for dataLayer injection when you can't modify source code directly.

Event Categories

Ecommerce:

• view_item, add_to_cart, remove_from_cart, view_cart
• begin_checkout, add_shipping_info, add_payment_info, purchase

Forms & Leads:

• form_submit, form_start, generate_lead

Engagement:

• scroll, file_download, search, outbound_click, share

Video:

• video_start, video_progress, video_complete

User:

• login, sign_up, page_view

Presets

Preset	Events Included
ecommerce	All 8 ecommerce events
engagement	Forms, scroll, downloads, video, search, sharing
all	Everything including page_view, login, sign_up

Generated Tag Features

• GA4-compliant dataLayer structure
• Ecommerce object clearing before pushes
• DOM scraping option for dynamic values
• Trigger recommendations and selectors
• Korean payment method support

Notion Integration

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

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

# Export with detailed content
python gtm_manager.py audit --url "https://example.com" --notion --notion-detailed

Environment Variables

export NOTION_TOKEN="secret_xxxxx"

Default Database

Default Notion database: OurDigital GTM Audit Log

Key Files

• gtm_manager.py - Main script with audit and inject functionality
• 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. Event Templates: Add new events to DataLayerInjector.EVENT_TEMPLATES
4. Form Selectors: Extend FormAnalyzer.discover_forms() for custom forms
5. 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 (장바구니, 결제하기, 주문하기)

Common Tasks

Add support for new tag platform

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

Add new event type for injection

# In DataLayerInjector.EVENT_TEMPLATES
"custom_event": {
    "description": "Track custom action",
    "params": {
        "custom_param": "/* value */",
    },
    "trigger": "Custom Trigger",
},

Extend checkout flow for specific platform

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