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](../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

```bash
# 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.

```bash
# 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

```bash
export NOTION_TOKEN="secret_xxxxx"
```

### Default Database

Default Notion database: [OurDigital GTM Audit Log](https://www.notion.so/2cf581e58a1e8163997fccb387156a20)

## 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
```python
# In TAG_DESTINATIONS dict
"NewPlatform": [
    r"tracking\.newplatform\.com",
    r"pixel\.newplatform\.com",
],
```

### Add new event type for injection
```python
# In DataLayerInjector.EVENT_TEMPLATES
"custom_event": {
    "description": "Track custom action",
    "params": {
        "custom_param": "/* value */",
    },
    "trigger": "Custom Trigger",
},
```

### Extend checkout flow for specific platform
```python
# In CheckoutFlowAnalyzer.detect_checkout_elements()
# Add platform-specific selectors
```