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

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