Here’s Fuel LAB‘s internal Data Layer blueprints designed for successful integration with the Google Marketing Platform. We use this daily as all of our integrations are done this way.
This documentation covers all the DataLayer Push for GTM and GA4; the syntax is compatible with all the products of the Google Marketing Platform.
This tracking blueprint will feature also non e-commerce items to include standard best practices.
Index
GA4 Events you can push with the DataLayer
Events are the core of the data layer push process. They allow you to track user behaviors or interactions with your website, such as clicking a button or view a product page. Events are triggered when the user performs an action, such as clicking a button or viewing a product page, and they can be used to capture data, including product data or user-specific data. Therefor, every implementation is different in terms of what triggers these events, trough datalayer pushes.
| Event | Example Trigger |
|---|---|
| view_promotion | Visualization of the promotional content on page; typically caused by the screen rendering of an element or group of elements tagged accordingly as promotion. |
| select_promotion | Click on a product contained in the tagged container “promotion” of your website, or any other placement dedicated to promotions. |
| view_item | Landing on a Woocommerce Product Page, Shopify Product page, and so on. |
| view_item_list | Visualization of any group of products; it could be the shop page, it could be the product selectors in the landing pages, it could be the cross sell grid of products on a product page.. that’s why using parameters like “item_list_id” is fundamental to accurately reading data. |
| select_item | Click pointing to the product page, be it from the item list in the shop page, or in any other product display placement. |
| select_category | This is a custom event we use to track collections and categories view, or landing page groups. |
| view_category | Another custom event we use to track the count of views of a specific category content. |
| add_to_cart | When a click performs an add to cart. |
| remove_from_cart | When an item is removed from the cart. |
| view_cart | Pageview of the cart page. |
| begin_checkout | Pageview of the checkout page. |
| add_payment_info | When the desired payment method has been selected. |
| purchase | On purhcase, on the order receipt page. |
| user_login | When a user logs in. |
| user_signup | When a visitor becomes a user, creating an account. |
| menu_click | This is a custom event. Triggered when menu items are clicked on. |
| generate_lead | When a contact form is successfully sent. |
Ecommerce Parameters
The parameters to pass in custom events for Google Analytics 4 and Google Ads are important for tracking user interactions and understanding user behaviour on your website. These events can help you gain insights into user behaviour, track conversions, and measure the success of your marketing campaigns. Notably, they are fundamental also for Google Ads’s campaigns to optimize correctly (depending on your usage of audiences, and micro conversions).
The parameters that can be passed in for DataLayer pushed events include, as an example:
- ecommerce: An object containing information about the user’s purchase (e.g. the items purchased, the currency, and the total value of the purchase).
- currency: The currency in which the purchase was made (e.g. EUR).
- value: The total value of the purchase.
- items: An array of objects containing parametric information about each item purchased (e.g. item_id, item_name, item_category, etc.).
- authenticationMethod: The method used to authenticate the user (e.g. email).
- userId: An identifier for the user (e.g. abc123).
- userType: The type of user (e.g. Free User).
- item_list_id: An identifier for the list of items purchased.
- item_list_name: The name of the list of items purchased.
- listposition: The position of the item in the list of items purchased.
- coupon: The coupon code used for the purchase (if any).
- discount: The discount amount applied to the purchase (if any).
Deepening the syntax and structure of the Data Layer, we find product data, promotion data and action data.
Product Data
| Parameter | Description |
|---|---|
| item_id | ID / SKU of the product. |
| item_name | Name of the product. |
| item_list_name | Product list name. |
| item_list_id | Product list identifier. |
| index | Product position in the list. |
| item_brand | Product brand. |
| item_category | Product category top-level. |
| item_category2 | Product category 2nd level (or alternative). |
| item_category3 | Product category 3rd level (or alternative). |
| item_category4 | Product category 4th level (or alternative). |
| item_category5 | Product category 5th level (or alternative). |
| item_variant | Item variant name or description. |
| affiliation | The store affiliation for this event. |
| discount | Any discount associated with this product. |
| coupon | Coupon associated with this product. |
| price | Price of this product. |
| currency | Currency of the price that is collected. |
| quantity | Quantity of the item. Must be an integer. |
Promotion Data
| Parameter | Description |
|---|---|
| promotion_id | ID of the promotion. |
| promotion_name | Name of the promotion. |
| creative_name | Name of the creative associated with the promotion. |
| creative_slot | Name of the slot where the creative was shown. |
| location_id | The physical location associated with the item. It’s recommended to use the Google Place ID that corresponds to the location. |
Action Data
| Parameter | Description |
|---|---|
| transaction_id | Unique ID for the transaction. Required for purchase and refund events. |
| affiliation | The store or affiliation where the purchase occurred. |
| value | The value associated with the event. |
| currency | Local currency of the collected price. Required for purchase events. |
| tax | How much tax is included in the total revenue of the purchase. |
| shipping | Shipping costs included in the total revenue of the purchase. |
| items | Products associated with the event. |
| shipping_tier | The shipping tier used with add_shipping_info. |
| payment_type | The payment method sent with add_payment_info. |
| coupon | Coupon associated with the event. |
| promotion_id | ID of a promotion associated with the event. |
| promotion_name | Name of a promotion associated with the event. |
| creative_name | Name of a promotion creative associated with the event. |
| creative_slot | Name of the creative slot associated with the event. |
| location_id | The physical location associated with the item. It’s recommended to use the Google Place ID that corresponds to the location. |
| item_list_name | Name of the list associated with the event. |
| item_list_id | ID of the list associated with the event. |
| form_id | The forminator Form ID |
| form_name | The forminator Form Name |
| form_type | sales, support |
Practical Data Layer Push Examples
Here’s our Data Layer pushes; obviously the rendered data is dummy-text that will change reflecting your ecommerce or website’s content, accordingly to implementation.
🚨 We recommend using the following command to delete the e-commerce object before executing a push of an e-commerce event at the data level. The deletion of the object will prevent multiple e-commerce events on a page from affecting each other.
Link to Documentation: https://developers.google.com/analytics/devguides/collection/ga4/ecommerce?hl=it&client_type=gtm
dataLayer.push({ ecommerce: null }); // Clear the previous ecommerce object.JavaScript
dataLayer.push({ ecommerce: null }); // Clear the previous ecommerce object.Menu Click
Custom Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "menu_click",
ecommerce: {
currency: "EUR",
items: {
menudata_item_listposition: 1,
menudata_item_url: "https://exampleurl.com/",
menudata_item_category: "Jackets",
menudata_item_name: "Discover Field Jackets - Made in Italy",
menudata_item_id: 34789 } },
})View Promotion
Recommended Event
dataLayer.push({ ecommerce: null });
dataLayer.push({
event: 'view_promotion',
ecommerce: {
promotion_id: 'yourPromoId1',
promotion_name: 'Jackets_Cyber_Monday23',
creative_name: 'Happy_Family_Wearing_Jackets',
creative_slot: 'featured_promotions',
location_id: 'hero_slider',
currency: "EUR",
items: [{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: "230"
}],
}
});Select Promotion
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'select_promotion',
ecommerce: {
promotion_id: 'yourPromoId1',
promotion_name: 'Jackets_Cyber_Monday23',
creative_name: 'Happy_Family_Wearing_Jackets',
creative_slot: 'featured_promotions',
location_id: 'hero_slider',
currency: "EUR",
items: [{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: "230"
}],
});View Item
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "view_item",
ecommerce: {
currency: "EUR",
value: "49",
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: "230"
},
})View Item List
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "view_item_list",
ecommerce: {
item_list_id: "related_products", // This will require custom ids or classes on your backend
item_list_name: "Related products", // This will require custom ids or classes on your backend
currency: "EUR",
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
},
{
item_id: 345798,
item_name: "Air Max Shoes",
item_brand: "Nike",
price: 229.00,
item_category: "Footwear",
index: 1,
google_business_vertical: "retail",
id: 345798
},
{
item_id: 368784,
item_name: "Jordan Shoes",
item_brand: "Nike",
item_variant: "Limited Edition Orange",
price: 1900.00,
item_category: "Footwear",
index: 1,
google_business_vertical: "retail",
id: 368784
},
{
item_id: 357715,
item_name: "Leather Jacket Reneaged",
item_brand: "Diesel",
price: 660.00,
item_category: "Jackets",
index: 1,
google_business_vertical: "retail",
id: 357715
},
{
item_id: 302108,
item_name: "Biker Wallet 01299",
item_brand: "Diesel",
price: 104.00,
item_category: "Accessories",
index: 1,
google_business_vertical: "retail",
id: 302108
},
{
item_id: 440,
item_name: "Sport Watch Band - Silicone",
item_brand: "Apple",
price: 65.00,
item_category: "Accessories",
index: 1,
google_business_vertical: "retail",
id: 440
}
]
},
})Select Item
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "select_item",
ecommerce: {
currency: "EUR",
items: [
{
item_id: 368784,
item_name: "Jordan Shoes",
item_brand: "Nike",
item_variant: "Limited Edition Orange",
price: 1900.00,
item_category: "Footwear",
index: 1,
google_business_vertical: "retail",
id: 368784
},
})Select Category
Custom Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "view_item",
ecommerce: {
currency: "EUR",
value: 49,
items: [
{
item_id: 368784,
item_name: "Jordan Shoes",
item_brand: "Nike",
item_variant: "Limited Edition Orange",
price: 1900.00,
item_category: "Footwear",
index: 1,
google_business_vertical: "retail",
id: 368784
},
})View Category
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "view_category",
pageType: "Landing Page",
pageTitle: "Jackets - Outdoors and Indoors",
visitorLoginState: "notLogged",
pageCategory: "Jackets",
ecommerce: {
currency: "EUR",
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
},
{
item_id: 345798,
item_name: "Air Max Shoes",
item_brand: "Nike",
price: 229.00,
item_category: "Footwear",
index: 1,
google_business_vertical: "retail",
id: 345798
}
]
},
})Add to Cart
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "add_to_cart",
ecommerce: {
currency: "EUR",
value: 98,
items: [
{
productlist_name: "Landing page",
listposition: "1",
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 98.00,
item_category: "Sports Set",
item_variant: "hello kitty set",
index: 1,
google_business_vertical: "retail",
id: 217
},
]
},
})Remove From Cart
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "remove_from_cart",
currency: "EUR",
value: 122.9,
ecommerce: {
items: [
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 98.00,
item_category: "Sports Set",
item_variant: "hello kitty set",
index: 1,
google_business_vertical: "retail",
id: 217
}
]
},
})View Cart
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "view_cart",
ecommerce: {
currency: "EUR",
value: "122.90",
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
}
]
},
})Begin Checkout
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "begin_checkout",
ecommerce: {
currency: "EUR",
value: 122.9,
coupon: "some_coupon",
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
}
]
},
})Add Payment Info
Recommended Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'add_payment_info',
ecommerce: {
payment_type: 'PayPal', // o CDC, o quello che vogliamo
currency: "EUR",
value: 122.9,
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
}
]
},
})Purchase (with Enhanced Conversion data)
Conversion Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
new_customer: false, (boolean
event: "purchase",
ecommerce: {
currency: "EUR",
transaction_id: "IT-402902",
discount: "somediscount"
coupon: "somecoupon",
affiliation: "",
value: 134,
items: [
{
item_id: 230,
item_name: "Field Jacket Dora",
item_brand: "Crazy Butterfiles",
price: 49,
item_category: "Outdoor Jackets",
item_variant: "Nylon FJM Ruby Red",
quantity: 2,
google_business_vertical: "retail",
id: 230
},
{
item_id: 217,
item_name: "Running Trousers Dora",
item_brand: "Crazy Butterfiles",
price: 23.00,
item_category: "Sports Set",
index: 1,
google_business_vertical: "retail",
id: 217
}
],
userdata:{
user_type: private,professional (boolean),
email: "123@google.com",
name: "pietro",
surname: "mingotti",
address: "strada del datalayer 155",
city: "Vicenza",
country: "Italy",
zip: "36100",
phone: "00393201124822"
},
},
})User Login
Advanced Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
'event' : 'login',
'authenticationMethod' : 'email',
'userId' : 'abc123' //this should be replaced with an actual ID
});User Signup
Advanced Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
'event': 'signup',
'userType': 'Free User'
});Generate Lead (with Enhanced Conversion Data)
Conversion Event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'generate_lead',
form_id: 'form id',
form_name: 'form name',
form_type: 'support or sales or else',
pageType: "",
pageTitle: "",
pagePath: "",
userdata:{
user_type: private,professional (boolean),
email: "123@google.com",
name: "pietro",
surname: "mingotti",
address: "strada del datalayer 155",
city: "Vicenza",
country: "Italy",
zip: "36100",
phone: "00393201124822"
},
});The items Array
It is important to consider that the “items” Array, within “ecommerce”, can populate all these fields (example data).
JavaScript
items: [
{item_id: "SKU_12345",
item_name: "Jordan Crazy Shoes",
affiliation: "",
coupon: "COUPON_TEST",
currency: "EUR",
discount: 12.22,
index: 1,
item_brand: "Nike",
item_category: "Footwear",
item_list_id: "homepage_widget",
item_list_name: "Homepage Widget",
item_variant: "Jordan Autograph Red",
price: 119.99,
quantity: 1
},
{...}]Non-Ecommerce Parameters
Here’s a list of parameters not necessarily linked to e-commerce tracking, but valuable to enhance you e-commerce tracking.
| Parameter | Description |
|---|---|
| pageType | Type of page (e.g. home page, product page, category page, etc.) |
| pageTitle | Title of the page |
| pageCategory | Category of the page (e.g. men’s clothing, electronics, etc.) |
| pagePath | Path of the page (e.g. /category/mens-clothing/shirts) |
| pageLanguage | Language of the page |
| pageLocation | Geographical location of the page (e.g. country, state, city) |
| visitorId | Unique identifier for the visitor |
| visitorType | Type of visitor (e.g. new visitor, returning visitor, etc.) |
| visitorLoginState | Whether the visitor is logged in or not |
| visitorAgeRange | Age range of the visitor |
| visitorGender | Gender of the visitor |
| deviceType | Type of device used to access the website (e.g. desktop, mobile, tablet) |
| browserType | Type of web browser used by the visitor |
| browserVersion | Version of the web browser used by the visitor |
| OS | Operating system used by the visitor |
Base DataLayer Content
The DataLayer, without specific triggers, must populate these information at every page load:
JavaScript
{
pageType:,
pageTitle:,
pageCategory:,
visitorLoginState:,
ecommerce:{
currency:,
items:,
}}
The typical data values for pageType are:
JavaScript
if (is_front_page()) $pageType = 'frontpage';
if (is_page()) $pageType = 'page';
if (is_single()) $pageType = 'post';
if (is_category()) $pageType = 'category';
if (is_tag()) $pageType = 'tag';
if (is_author()) $pageType = 'author';
if (is_search()) $pageType = 'search';
if (is_404()) $pageType = '404';
if (is_archive()) $pageType = 'archive';
if (is_shop()) $pageType = 'shop';
if (is_product()) $pageType = 'product';
if (is_product_category()) $pageType = 'product_category';
if (is_product_tag()) $pageType = 'product_tag';
if (is_cart()) $pageType = 'cart';
if (is_checkout()) $pageType = 'checkout';
if (is_checkout() && !empty(is_wc_endpoint_url('order-received'))) $dataLayer['pagePostType'] = 'purchase';
if (is_account_page()) $pageType = 'account';
if (is_order_received_page()) $pageType = 'order_received';
if ($pageTemplate == 'views/template-landing-page.blade.php') $pageType = 'product';How to push the DataLayer
I hope our blueprints were useful for your debug or implementation sessions. It’s impossible to depict “how to push the data layer”, without looking at your specific website. Feel free to press the floating button on this page to request a meeting and an implementation.
However, something to start with a basic tracking, if you’re using WordPress with WooCommerce, would be the Google Tag Manager for WordPress plugin. Many websites use it, it’s well done and lightweight.
Pietro Mingotti is an Italian entrepreneur and digital marketing specialist, best known as the founder and owner of Fuel LAB, a leading digital marketing and technical marketing agency based in Italy, operating worldwide. With a passion for creativity, innovation, and technology, Pietro has established himself as a thought leader in the field of digital marketing and has helped numerous companies achieve their marketing goals.