Data layer implementation guide for web tracking

General guidelines

This article provides detailed guidelines for implementing the necessary data layer events to enable effective tracking of user interactions on your e-commerce website. By following this guide, you will understand what data needs to be captured, how it should be structured, and when it should be sent. The implementation aligns with Google’s recommended event names and data structures for e-commerce tracking.

Event names: You can use the event names suggested by Google Analytics to maintain consistency or your own names.

Data layer: All events should be pushed to the dataLayer object.

Currency: Use three-letter ISO 4217 currency codes (e.g., “USD”).

Properties: Ensure all properties are accurately captured as per the specifications.

User data: Include hashed user data when users are logged in.

Product consistency across events

For accurate tracking and data analysis, it is critical that product information remains consistent across all events where a product is involved. Specifically, the item_id and other key product attributes must remain the same in all events that reference the same product. For example:

• If a user visits a product detail page and the view_item event is triggered, and later adds that same product to their cart, the item_id in the view_item and add_to_cart events must be identical.
• The same rule applies for events like remove_from_cart, view_cart, and purchase where the product is referenced.

What to ensure:

• item_id remains consistent across all events for the same product.
• Other product details such as productGroupId, productName, and price should also be consistent.

By maintaining consistency, it ensures that user actions related to a specific product are accurately tracked across the customer journey, from viewing a product to purchasing it.

Leveraging existing Google Analytics integrations

Most e-commerce stores already have a Google Analytics integration in place for tracking user interactions like product views, add-to-cart actions, and purchases. The events required for our marketing automation tracking tool align with these commonly used Google Analytics e-commerce events, which means in many cases, no new events need to be created.

However, we have noticed that some stores may have configured this tracking incorrectly, which could lead to incomplete or inaccurate data collection. To ensure the best results with our tracking script, you should verify that the existing event configuration is implemented correctly based on the data layer guidelines provided.

Option for event prefix (_ecdp)

If you prefer to keep the existing Google Analytics setup untouched or if you want to create separate events specifically for our platform, you can simply add the prefix _ecdp to each event. For example:

• view_item → _ecdp_view_item
• add_to_cart → _ecdp_add_to_cart
• remove_from_cart → _ecdp_remove_from_cart
• view_cart → _ecdp_view_cart
• purchase → _ecdp_purchase

This approach allows you to keep a separate data stream for our platform while still using the existing configuration. The core event structure remains the same, ensuring minimal additional work for developers.

Required events

• view_item
• add_to_cart
• remove_from_cart
• view_cart
• purchase

Additional events for wishlist functionality (if applicable)

• add_to_wishlist
• remove_from_wishlist
• view_wishlist

Data layer event specifications

Product detail view (view_item)

Fired when a user views a product detail page or selects a different product variant (e.g., size, color).

When to fire:

• On initial product detail page load.
• When a user selects a different product configuration.

Data structure

dataLayer.push({
  "event": "view_item",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",                   // productId
      "item_group_id": "group123",           // productGroupId (if applicable)
      "item_variant": "BA1234_43",           // productIdV2 (if applicable)
      "item_name": "Adidas Stan Smith",      // productName
      "price": 100.00,                       // salePrice
      "original_price": 120.00,              // originalPrice
      "omnibus_price": 95.00,                // omnibusPrice (if applicable)
      "currency": "USD",
      "item_category": "Shoes",              // First category
      "item_category2": "Men",               // Second category (if applicable)
      "item_category3": "Sneakers",          // Third category (if applicable)
      "image_url": "https://example.com/images/adidas-stan-smith.jpg",
      "availability": true            // isAvailable (use "true"/"false")
    }]
  }
});

Property definitions:

• item_id: Unique product identifier.
• item_group_id: Unique product group identifier.
• item_variant: Unique product variant identifier.
• item_name: Product name as displayed to the user.
• price: Current sale price of the product.
• original_price: Original price before any discounts.
• omnibus_price: Historical lowest price in the last 30 days (if applicable).
• item_category: Primary product category.
• image_url: URL of the product image.
• availability: “true” or “false”.

Notes:

• Include original_price and price even if they are the same (when no discount applies).
• omnibus_price should be included if available; otherwise, it can be omitted or set to null.
• item_category2 and item_category3 are optional and can include subcategories.
• Ensure that the item_id remains the same across subsequent events such as add_to_cart or purchase for this product.

Product variant selection (select_item)

Description:

• Fired when a user selects a different variant of a product on the product detail page.

When to fire:

• When a user changes the product configuration (e.g., selects a different size or color).

Data structure

dataLayer.push({
  "event": "select_item",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",
      "item_group_id": "group123",
      "item_variant": "BA1234_44",
      "item_name": "Adidas Stan Smith Size 44",
      "price": 100.00,
      "original_price": 120.00,
      "omnibus_price": 95.00,
      "currency": "USD",
      "item_category": "Shoes",
      "item_category2": "Men",
      "item_category3": "Sneakers",
      "image_url": "https://example.com/images/adidas-stan-smith-44.jpg",
      "availability": true
    }]
  }
});

Notes:

• This event helps track user preferences for different product configurations.
• Ensure that the item_variant property reflects the selected variant.

Add to dart (add_to_cart)

Description:

• Fired when a user adds one or more products to their shopping cart.

When to fire:

• When the user confirms adding a product to the cart.

Data structure:

dataLayer.push({
  "event": "add_to_cart",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",
      "item_group_id": "group123",
      "item_variant": "BA1234_43",
      "item_name": "Adidas Stan Smith",
      "price": 100.00,
      "original_price": 120.00,
      "omnibus_price": 95.00,
      "quantity": 1
    }]
  }
});

• quantity: Number of units added to the cart (should be a positive integer).

Notes:

• Include all relevant product properties as in the view_item event.
• If multiple products are added at once, include each product in the items array.
• Ensure the item_id in this event is consistent with the item_id used in the view_item event for the same product.

Remove from cart (remove_from_cart)

Description:

• Fired when a user removes one or more products from their shopping cart.

When to fire:

• When the user confirms removing a product from the cart.
• When the user removes multiple products or clears the entire cart. In this case, the event should capture all the removed products in a single remove_from_cart event, where each removed product is listed in the items array

Data structure:

dataLayer.push({
  "event": "remove_from_cart",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",
      "item_group_id": "group123",
      "item_variant": "BA1234_43",
      "item_name": "Adidas Stan Smith",
      "price": 100.00,
      "original_price": 120.00,
      "omnibus_price": 95.00,
      "quantity": 1
    }]
  }
});

Notes:

• Ensure that the remove_from_cart event supports multiple product removals. If a user removes several products or clears the entire cart, include each removed product in the items array, as shown below:
• Quantity should be an integer representing the number of units removed.
• Ensure that all other product details are consistent with previous events (e.g., item_id, item_variant, price).

View cart (view_cart)

Description:

• Fired when a user views the shopping cart or proceeds to the checkout.

When to fire:

• On the shopping cart page load.
• On the initial step of the checkout process.

Data structure

dataLayer.push({
  "event": "view_cart",
  "ecommerce": {
    "currency": "USD",
    "items": [
      {
        "item_id": "BA1234",
        "item_group_id": "group123",
        "item_variant": "BA1234_43",
        "item_name": "Adidas Stan Smith",
        "price": 100.00,
        "original_price": 120.00,
        "omnibus_price": 95.00,
        "quantity": 2,
        "image_url": "https://example.com/images/adidas-stan-smith.jpg",
        "availability": true
      },
      {
        "item_id": "BA5678",
        "item_group_id": "group456",
        "item_name": "Nike Air Max",
        "price": 150.00,
        "original_price": 150.00,
        "quantity": 1,
        "image_url": "https://example.com/images/nike-air-max.jpg",
        "availability": true
      }
    ]
  }
});

Notes:

• Include all products currently in the cart.
• Ensure quantity reflects the current quantity of each product in the cart.

Begin checkout (begin_checkout)

Description:

• Fired when a user initiates the checkout process.

When to fire:

• On the first page of the checkout process.

Data structure:

dataLayer.push({
  "event": "begin_checkout",
  "ecommerce": {
    "currency": "USD",
    "items": [
      {
        "item_id": "BA1234",
        "item_group_id": "group123",
        "item_variant": "BA1234_43",
        "item_name": "Adidas Stan Smith",
        "price": 100.00,
        "original_price": 120.00,
        "omnibus_price": 95.00,
        "quantity": 2,
        "image_url": "https://example.com/images/adidas-stan-smith.jpg",
        "availability": true
      }
    ]
  }
});

Notes:

• This event is similar to view_cart but specifically indicates the start of the checkout process.

Purchase (purchase)

Description:

• Fired upon successful completion of a purchase.

When to fire:

• On the order confirmation page after a successful transaction.

Data structure

dataLayer.push({
  "event": "purchase",
  "ecommerce": {
    "transaction_id": "ORD78910",           // orderId
    "client_order_id": "GPDWMFE",           // clientOrderId (if applicable)
    "value": 250.00,                        // totalOrderCost
    "tax": 0.00,                            // Tax amount (if applicable)
    "shipping": 30.00,                      // orderShippingCost
    "currency": "USD",
    "items": [
      {
        "item_id": "BA1234",
        "item_group_id": "group123",
        "item_variant": "BA1234_43",
        "item_name": "Adidas Stan Smith",
        "price": 100.00,
        "quantity": 2
      },
      {
        "item_id": "BA5678",
        "item_group_id": "group456",
        "item_name": "Nike Air Max",
        "price": 150.00,
        "quantity": 1
      }
    ]
  }
});

Property definitions:

• transaction_id: Unique order identifier.
• client_order_id: Customer-facing order ID (if different from transaction_id).
• value: Total order cost including shipping and taxes.
• tax: Total tax amount (set to 0.00 if not applicable).
• shipping: Total shipping cost.

Notes:

• items array should include all products purchased.
• Ensure all product properties are accurately captured.
• If there are additional costs or discounts, adjust the value accordingly.

View wishlist (view_wishlist)

Description:

• Fired when a user views their wishlist.

Data structure:

dataLayer.push({
  "event": "view_wishlist",
  "ecommerce": {
    "currency": "USD",
    "items": [
      {
        "item_id": "BA1234",
        "item_group_id": "group123",
        "item_name": "Adidas Stan Smith",
        "price": 100.00,
        "image_url": "https://example.com/images/adidas-stan-smith.jpg",
        "availability": true
      }
    ]
  }
});

Add to wishlist (add_to_wishlist)

Description:

• Fired when a user adds a product to their wishlist.

Data structure:

dataLayer.push({
  "event": "add_to_wishlist",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",
      "item_group_id": "group123",
      "item_name": "Adidas Stan Smith",
      "price": 100.00
    }]
  }
});

Remove from wishlist (remove_from_wishlist)

Description:

• Fired when a user removes a product from their wishlist.

Data structure:

dataLayer.push({
  "event": "remove_from_wishlist",
  "ecommerce": {
    "currency": "USD",
    "items": [{
      "item_id": "BA1234",
      "item_group_id": "group123",
      "item_name": "Adidas Stan Smith",
      "price": 100.00
    }]
  }
});

User data

Description:

• Include user information when the user is logged in.
• Only one identifier is required!

Data structure:

dataLayer.push({
  "userData": {
    "email": "user@example.com",            // User's email (if permitted)
    "emailMd5": "md5hashvalue",             // MD5 hash of the email
    "emailSha256": "sha256hashvalue"        // SHA256 hash of the email
  }
});

Notes:

• The email address should be in lowercase before hashing.
• Storing the plaintext email is optional
• Hashing provides an additional layer of privacy protection.

Additional implementation details

Event timing:

• All events should be pushed to the dataLayer at the appropriate time, ensuring they are captured accurately.

Data consistency:

• Ensure that the same product identifiers and properties are used consistently across all events.

Currency formatting:

• Prices should be formatted as numbers with two decimal places.
• Always include the currency code in the currency property.

Product availability:

• Use “in stock” or “out of stock” for the availability property.
• This helps in understanding product demand and stock levels.

Implementation checklist

• Product detail view (view_item): Implemented on product detail pages with all required properties.
• Product variant selection (select_item): Implemented when users select different product configurations.
• Add to cart (add_to_cart): Implemented when products are added to the cart.
• Remove from cart (remove_from_cart): Implemented when products are removed from the cart.
• View cart (view_cart): Implemented on the shopping cart page.
• Begin checkout (begin_checkout): Implemented at the start of the checkout process.
• Purchase (purchase): Implemented on the order confirmation page.
• Wishlist events: Implemented if the wishlist functionality is available.
• User data: Implemented for logged-in users with appropriate hashing.

Refrences

• Google Analytics E-Commerce Tracking
• ISO 4217 Currency Codes