our-claude-skills/custom-skills/62-gtm-guardian/code/references/datalayer-schema.md

# DataLayer Schema Reference

GA4 권장 이벤트 기반 DataLayer 스키마 정의.

## Core Principles

1. GTM 스니펫 이전에 dataLayer 초기화
2. 이벤트 발생 시점에 push (사전 아님)
3. ecommerce 객체는 push 전 clear 필수
4. PII 데이터 직접 수집 금지

## Base Structure

### Page Load
```javascript
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'event': 'page_data',
  'page': {
    'type': 'home|category|product|cart|checkout|thankyou|content|search',
    'name': 'Page Name',
    'category': 'Category/Subcategory',
    'language': 'ko'
  },
  'user': {
    'status': 'logged_in|logged_out',
    'id': 'hashed_user_id',           // SHA256, 로그인 시에만
    'type': 'new|returning|member|guest',
    'loginMethod': 'email|kakao|naver|google'
  }
});
```

## E-commerce Events

### view_item
```javascript
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'view_item',
  'ecommerce': {
    'currency': 'KRW',
    'value': 29000,
    'items': [{
      'item_id': 'SKU_12345',
      'item_name': 'Product Name',
      'item_brand': 'Brand Name',
      'item_category': 'Category',
      'item_variant': 'Blue / Large',
      'price': 29000,
      'quantity': 1
    }]
  }
});
```

### add_to_cart
```javascript
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {
    'currency': 'KRW',
    'value': 29000,
    'items': [{
      'item_id': 'SKU_12345',
      'item_name': 'Product Name',
      'price': 29000,
      'quantity': 1
    }]
  }
});
```

### begin_checkout
```javascript
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'begin_checkout',
  'ecommerce': {
    'currency': 'KRW',
    'value': 58000,
    'coupon': 'WELCOME10',
    'items': [/* cart items */]
  }
});
```

### purchase
```javascript
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': 'T_20250115_001',
    'affiliation': 'Store Name',
    'value': 53000,
    'tax': 4818,
    'shipping': 3000,
    'currency': 'KRW',
    'coupon': 'WELCOME10',
    'items': [{
      'item_id': 'SKU_12345',
      'item_name': 'Product Name',
      'price': 29000,
      'quantity': 1
    }]
  }
});
```

## Lead Gen Events

### generate_lead
```javascript
dataLayer.push({
  'event': 'generate_lead',
  'currency': 'KRW',
  'value': 50000,
  'lead': {
    'source': 'contact_form|landing_page',
    'type': 'inquiry|quote_request'
  }
});
```

### form_submit
```javascript
dataLayer.push({
  'event': 'form_submit',
  'form': {
    'id': 'contact_form',
    'name': 'Contact Us Form',
    'type': 'contact',
    'success': true
  }
});
```

## Engagement Events

### login / sign_up
```javascript
dataLayer.push({
  'event': 'login',  // or 'sign_up'
  'method': 'email|kakao|naver|google'
});
```

### search
```javascript
dataLayer.push({
  'event': 'search',
  'search_term': 'user search query',
  'search': {
    'results_count': 42,
    'category': 'product|content'
  }
});
```

## Item Object Reference

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| item_id | string | Yes | SKU |
| item_name | string | Yes | 상품명 |
| price | number | Yes | 단가 |
| quantity | number | Yes | 수량 |
| item_brand | string | No | 브랜드명 |
| item_category | string | No | 카테고리 |
| item_category2-5 | string | No | 하위 카테고리 |
| item_variant | string | No | 옵션 |
| coupon | string | No | 쿠폰 코드 |
| discount | number | No | 할인 금액 |
| index | number | No | 목록 위치 |

## Validation Rules

```javascript
// ✅ Correct
'price': 29000        // number
'quantity': 1         // number
'currency': 'KRW'     // uppercase

// ❌ Wrong
'price': '29000'      // string
'currency': 'krw'     // lowercase
```

### Array Limits
- items[]: 최대 200개
- 초과 시 분할 전송