# 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

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

### Add custom form field detection
```python
# In FormAnalyzer.discover_forms()
# Add new field types or selectors
```

### Extend checkout flow for specific platform
```python
# 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