289 lines
6.5 KiB
Markdown
289 lines
6.5 KiB
Markdown
# E-commerce Event Testing in DebugView
|
||
|
||
## Complete E-commerce Flow
|
||
|
||
### 1. view_item_list
|
||
|
||
**Fires:** Product listing page loads
|
||
|
||
**Required Parameters:**
|
||
- `item_list_id`: "related_products", "search_results"
|
||
- `item_list_name`: "Related Products", "Search Results"
|
||
- `items`: Array of products shown
|
||
|
||
**Validation:**
|
||
- [ ] Items array populated
|
||
- [ ] Each item has item_id and item_name
|
||
- [ ] item_list_id and item_list_name present
|
||
|
||
### 2. select_item
|
||
|
||
**Fires:** User clicks product from list
|
||
|
||
**Required Parameters:**
|
||
- `item_list_id`: Same as view_item_list
|
||
- `item_list_name`: Same as view_item_list
|
||
- `items`: Array with selected item
|
||
|
||
**Validation:**
|
||
- [ ] Only selected item in items array
|
||
- [ ] item_list matches where user clicked from
|
||
|
||
### 3. view_item
|
||
|
||
**Fires:** Product detail page loads
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Product price
|
||
- `items`: Array with single product
|
||
|
||
**Validation:**
|
||
- [ ] currency present
|
||
- [ ] value is number
|
||
- [ ] items[0] contains full product details
|
||
|
||
### 4. add_to_cart
|
||
|
||
**Fires:** User adds item to cart
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Item total (price × quantity)
|
||
- `items`: Array with added item(s)
|
||
|
||
**Validation:**
|
||
- [ ] value = price × quantity
|
||
- [ ] currency matches site currency
|
||
- [ ] items array has correct item
|
||
- [ ] quantity is integer
|
||
|
||
### 5. remove_from_cart (Optional)
|
||
|
||
**Fires:** User removes item from cart
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Removed item value
|
||
- `items`: Array with removed item
|
||
|
||
### 6. view_cart (Optional)
|
||
|
||
**Fires:** Cart page loads
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Total cart value
|
||
- `items`: All items in cart
|
||
|
||
### 7. begin_checkout
|
||
|
||
**Fires:** Checkout process starts
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Cart total
|
||
- `items`: All items in cart
|
||
- `coupon` (if applicable)
|
||
|
||
**Validation:**
|
||
- [ ] value matches cart total
|
||
- [ ] All cart items in items array
|
||
- [ ] coupon code if applied
|
||
|
||
### 8. add_payment_info (Optional)
|
||
|
||
**Fires:** Payment method added
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Transaction value
|
||
- `payment_type`: "credit_card", "paypal", etc.
|
||
|
||
### 9. add_shipping_info (Optional)
|
||
|
||
**Fires:** Shipping info added
|
||
|
||
**Required Parameters:**
|
||
- `currency`: "USD"
|
||
- `value`: Transaction value
|
||
- `shipping_tier`: "Ground", "Express", etc.
|
||
|
||
### 10. purchase
|
||
|
||
**Fires:** Transaction completes
|
||
|
||
**Required Parameters:**
|
||
- `transaction_id`: UNIQUE order ID
|
||
- `currency`: "USD"
|
||
- `value`: Total revenue
|
||
- `items`: All purchased items
|
||
|
||
**Optional Parameters:**
|
||
- `tax`: Tax amount
|
||
- `shipping`: Shipping cost
|
||
- `coupon`: Coupon code
|
||
- `affiliation`: Store name
|
||
|
||
**Validation:**
|
||
- [ ] transaction_id is unique (never reused)
|
||
- [ ] value is total (items + tax + shipping - discounts)
|
||
- [ ] All items have complete details
|
||
- [ ] tax and shipping are numbers
|
||
- [ ] No duplicate purchase events
|
||
|
||
### 11. refund (Optional)
|
||
|
||
**Fires:** Transaction refunded
|
||
|
||
**Required Parameters:**
|
||
- `transaction_id`: Original order ID
|
||
- `currency`: "USD"
|
||
- `value`: Refund amount
|
||
|
||
## Items Array Structure
|
||
|
||
**Complete Item Object:**
|
||
|
||
```javascript
|
||
{
|
||
"item_id": "SKU_12345", // Required
|
||
"item_name": "Blue T-Shirt", // Required
|
||
"affiliation": "Online Store",
|
||
"coupon": "SUMMER20",
|
||
"currency": "USD",
|
||
"discount": 2.00,
|
||
"index": 0, // Position in list
|
||
"item_brand": "MyBrand",
|
||
"item_category": "Apparel",
|
||
"item_category2": "Men",
|
||
"item_category3": "Shirts",
|
||
"item_category4": "T-Shirts",
|
||
"item_category5": "Short Sleeve",
|
||
"item_list_id": "related_products",
|
||
"item_list_name": "Related Products",
|
||
"item_variant": "Blue",
|
||
"location_id": "Warehouse_A",
|
||
"price": 29.99, // Required for most events
|
||
"quantity": 2 // Required for cart/purchase events
|
||
}
|
||
```
|
||
|
||
## Testing Purchase Event
|
||
|
||
**Complete Test:**
|
||
|
||
1. **Add items to cart** → Verify `add_to_cart` for each
|
||
2. **Go to checkout** → Verify `begin_checkout`
|
||
3. **Complete purchase** → Verify `purchase`
|
||
|
||
**Purchase Event Checklist:**
|
||
|
||
- [ ] Event name: `purchase`
|
||
- [ ] `transaction_id` present and unique
|
||
- [ ] `value` is number (not string)
|
||
- [ ] `currency` is 3-letter code
|
||
- [ ] `items` array not empty
|
||
- [ ] Each item has `item_id`
|
||
- [ ] Each item has `item_name`
|
||
- [ ] Each item has `price` (number)
|
||
- [ ] Each item has `quantity` (integer)
|
||
- [ ] Optional: `tax` is number
|
||
- [ ] Optional: `shipping` is number
|
||
- [ ] Optional: `coupon` is string
|
||
- [ ] No duplicate `transaction_id` in DebugView session
|
||
|
||
**Common Issues:**
|
||
|
||
**Issue:** Items array empty
|
||
- **Cause:** Items not passed to event
|
||
- **Fix:** Ensure dataLayer.push includes ecommerce.items
|
||
|
||
**Issue:** Value is string "99.99"
|
||
- **Cause:** Quotes around number
|
||
- **Fix:** Remove quotes: `value: 99.99`
|
||
|
||
**Issue:** transaction_id repeats
|
||
- **Cause:** Page reload after purchase, or testing with same ID
|
||
- **Fix:** Generate unique IDs, prevent double-submit
|
||
|
||
**Issue:** Item missing price
|
||
- **Cause:** Incomplete item object
|
||
- **Fix:** Include price in every item object
|
||
|
||
## Calculating Value
|
||
|
||
**Formula:**
|
||
```
|
||
value = (sum of item prices × quantities) + tax + shipping - discount
|
||
```
|
||
|
||
**Example:**
|
||
```javascript
|
||
Item 1: $29.99 × 2 = $59.98
|
||
Item 2: $19.99 × 1 = $19.99
|
||
Subtotal: $79.97
|
||
Tax: $6.40
|
||
Shipping: $5.00
|
||
Discount: -$10.00
|
||
Total value: $81.37
|
||
```
|
||
|
||
**In DebugView:**
|
||
```
|
||
purchase event:
|
||
value: 81.37
|
||
currency: "USD"
|
||
tax: 6.40
|
||
shipping: 5.00
|
||
items: [item1, item2]
|
||
```
|
||
|
||
## Multi-Step Checkout Validation
|
||
|
||
**Step 1: Cart Page**
|
||
- `view_cart` event
|
||
- Items match current cart
|
||
- Value correct
|
||
|
||
**Step 2: Shipping Info**
|
||
- `add_shipping_info` event
|
||
- shipping_tier parameter
|
||
- Value includes shipping
|
||
|
||
**Step 3: Payment Info**
|
||
- `add_payment_info` event
|
||
- payment_type parameter
|
||
- Value matches total
|
||
|
||
**Step 4: Review Order**
|
||
- No specific event (or custom event)
|
||
- Final verification before purchase
|
||
|
||
**Step 5: Purchase Complete**
|
||
- `purchase` event
|
||
- Unique transaction_id
|
||
- All parameters correct
|
||
- Confirmation page loads
|
||
|
||
## Testing with Test Transactions
|
||
|
||
**Using GTM Preview + DebugView:**
|
||
|
||
1. Enable GTM Preview mode
|
||
2. Enable DebugView
|
||
3. Add test product to cart
|
||
4. Complete checkout with test payment
|
||
5. Verify each event in real-time:
|
||
- **GTM Tag Assistant:** Tags fire
|
||
- **DebugView:** Events appear
|
||
6. Cross-check parameters match
|
||
7. Verify transaction_id is unique
|
||
8. Test refund event (if implemented)
|
||
|
||
**Best Practice:**
|
||
- Use test payment gateway in development
|
||
- Generate unique transaction_ids for each test
|
||
- Document test transaction IDs
|
||
- Clean up test data if it reaches production
|