our-claude-skills/ourdigital-custom-skills/14-ourdigital-gtm-manager/docs/ga4_events.md

# GA4 Recommended Events Reference

## Automatically Collected Events
Events GA4 collects without configuration:
- `first_visit` - First time user visits
- `session_start` - Session begins
- `page_view` - Page loads (enhanced measurement)
- `scroll` - 90% scroll depth
- `click` - Outbound link clicks
- `file_download` - File download clicks
- `video_start`, `video_progress`, `video_complete` - YouTube embeds

## E-commerce Events (Required Parameters)

### view_item_list
```javascript
{
  event: "view_item_list",
  ecommerce: {
    item_list_id: "related_products",
    item_list_name: "Related Products",
    items: [{
      item_id: "SKU_12345",      // required
      item_name: "Product Name", // required
      price: 29.99,
      quantity: 1
    }]
  }
}
```

### view_item
```javascript
{
  event: "view_item",
  ecommerce: {
    currency: "USD",
    value: 29.99,
    items: [{
      item_id: "SKU_12345",      // required
      item_name: "Product Name", // required
      price: 29.99,
      quantity: 1
    }]
  }
}
```

### add_to_cart
```javascript
{
  event: "add_to_cart",
  ecommerce: {
    currency: "USD",
    value: 29.99,
    items: [{
      item_id: "SKU_12345",      // required
      item_name: "Product Name", // required
      price: 29.99,
      quantity: 1
    }]
  }
}
```

### begin_checkout
```javascript
{
  event: "begin_checkout",
  ecommerce: {
    currency: "USD",
    value: 99.99,
    coupon: "SUMMER_SALE",
    items: [...]
  }
}
```

### add_payment_info
```javascript
{
  event: "add_payment_info",
  ecommerce: {
    currency: "USD",
    value: 99.99,
    payment_type: "credit_card",
    items: [...]
  }
}
```

### purchase
```javascript
{
  event: "purchase",
  ecommerce: {
    transaction_id: "T12345",   // required, must be unique
    value: 99.99,               // required
    currency: "USD",            // required
    tax: 4.99,
    shipping: 5.99,
    coupon: "SUMMER_SALE",
    items: [{
      item_id: "SKU_12345",     // required
      item_name: "Product Name",// required
      price: 29.99,
      quantity: 2
    }]
  }
}
```

## Lead Generation Events

### generate_lead
```javascript
{
  event: "generate_lead",
  currency: "USD",
  value: 100  // estimated lead value
}
```

### sign_up
```javascript
{
  event: "sign_up",
  method: "email"  // or "google", "facebook", etc.
}
```

### login
```javascript
{
  event: "login",
  method: "email"
}
```

## Engagement Events

### search
```javascript
{
  event: "search",
  search_term: "blue shoes"
}
```

### share
```javascript
{
  event: "share",
  method: "twitter",
  content_type: "article",
  item_id: "article_123"
}
```

## Parameter Validation Rules

| Parameter | Type | Max Length | Notes |
|-----------|------|------------|-------|
| event name | string | 40 chars | No spaces, alphanumeric + underscore |
| item_id | string | 100 chars | Required for e-commerce |
| item_name | string | 100 chars | Required for e-commerce |
| currency | string | 3 chars | ISO 4217 format (USD, KRW, etc.) |
| transaction_id | string | 100 chars | Must be unique per transaction |
| value | number | - | Numeric, no currency symbols |

## Common Validation Errors

1. **Missing required params**: `item_id` or `item_name` not in items array
2. **Wrong data type**: `value` as string instead of number
3. **Duplicate transaction_id**: Same ID used for multiple purchases
4. **Empty items array**: E-commerce event with no items
5. **Invalid currency**: Currency code not in ISO 4217 format