Once you have installed the VTEX IO Google Tag Manager app, set it up in your store by configuring all the necessary variables, triggers, and tags.
If you are using the Google Tag Manager 2.x., we strongly recommend migrating to the major 3.x. Google Tag Manager 3.x tracks the entire user’s journey through the store, from viewing a product to purchasing it. Refer to Migrating Google Tag Manager app from major 2.x to major 3.x and follow the step-by-step.
Before you start
The VTEX IO GTM app is compliant with the Universal Analytics Enhanced Ecommerce events format, meaning it supports the following events:
- Product Impression;
- Product Click;
- Product Detail Impression;
- Add/Remove from Cart;
- Promotion Impression;
- Promotion Click;
- Checkout;
- Purchase.
GTM components trigger these events, allowing you to measure your store's data through. If you are not familiar with the GTM components, we strongly recommend checking the Google Tag Manager documentation before starting the setup.
ℹ To track the events related to the search use on your site in Google Analytics, learn how to set up Google Analytics search tracking in your VTEX IO store.
Follow the steps below to create all necessary GTM components for your store.
Step-by-step
Step 1 - Creating variables
Variables are little data points that you can use in tags or triggers to indicate when and where to fire a tag according to a trigger’s conditions. For example, you want to fire a tag on a page view, thus you need to decide if the tag will be fired on all page views or on a specific page.
To start, create the essential variables to work within GTM: Data Layer and Google Analytics settings.
-
Data Layer variables: store and deliver data from your website to the GTM. Data such as page title and URL, user ID, product ID, product price, etc.
-
Google Analytics settings variables: a template to set up Google Analytics tags in one place, instead of performing changes in each tag. These variables track page views, events, and ecommerce transactions.
- Open the Google Tag Manager dashboard.
- Click on Variables.
- In the User-Defined Variables box, click on New.
An error occurred while trying to load the image. https://raw.githubusercontent.com/vtexdocs/dev-portal-content/gtm-images-update/docs/vtex-io/Storefront-Guides/google-tag-manager/vtex-io-documentation-setting-up-google-tag-manager-0.webp
Data Layer Variables
- Click on the Variable Configuration box and select Data Layer Variable.
- Type
currency
in theData Layer Variable Name
field. - Click on
Save
and save it as Data Layer Variable - currency.
Repeat the instructions above, now changing the data layer variable name to each of the following variables, unless the Data Layer Variable - currency already declared in the example above:
Variable name | Value | Description | Tags that will use it |
---|---|---|---|
Data Layer Variable - currency | currency | Indicates the local currency for all transaction currency values. | Google Ads Conversion Tracking |
Data Layer Variable - transactionId | transactionId | Indicates a unique transaction identifier. | Google Ads Conversion Tracking |
Data Layer Variable - transactionTotal | transactionTotal | Indicates the total value transaction. | Google Ads Conversion Tracking |
Variable name | Value | Description | Variables that will use it |
---|---|---|---|
Data Layer Variable - userId | userId | Enables the association of one or more sessions with a unique and persistent ID for your store’s users. | Google Analytics |
ecommerceV2 | ecommerceV2 | Triggers events to track the entire user’s journey through the store, from viewing a product to purchasing it. This variable is part of the major 3.x of the GTM app. | Google Analytics - Checkout and Order Placed |
There are two other variables, The originalLocation
and originalReferrer
, that you must create to prevent GTM from making additional session identifiers every time a user navigates the website. Learn how to create them in the following steps.
Creating the Original Location and Original Referrer variables
Creating the following variables is important to persist campaign data throughout a user session and avoid inconsistent campaign data to Google Analytics (GA).
- On the container page, click on Variables.
- In the Built-In Variables section, check if the
Page URL
andPage Path
variables are enabled. Otherwise, click on Configure and select Page URL and Page Path to enable them. - Go to the User-Defined Variables section and click on
New
. A side popup will open. - Replace the
Untitled Variable
value withOriginal Location
. - Click on
Variable Configuration
. - On Page Variables, click on
Data Layer Variable
. - In the
Data Layer Variable Name
field, typeoriginalLocation
. - Enable the
Set Default Value
option and fill in theDefault Value
field with the following value:{{Page URL}}
.

- Click on
Save
.
Once you have saved the originalLocation
variable, create the originalReferrer
as described on the steps below:
- In the User-Defined Variables section, click on
New
. A side popup will open. - Replace the
Untitled Variable
value withOriginal Referrer
. - Click on
Variable Configuration
. - On Page Variables, click on
Data Layer Variable
. - In the
Data Layer Variable Name
field, typeoriginalReferrer
. - Enable the
Set Default Value
option and fill in theDefault Value
field with the following value:{{Referrer}}
.

- Click on
Save
.
Google Analytics Variables
You will create one variable for the storefront - default - and another for the store’s checkout.
Variable type | Description | Tags that will use it |
---|---|---|
Default - For storefront | Tracks the page’s view. | Google Analytics - Enhanced Ecommerce - No Interaction , Google Analytics - Enhanced Ecommerce - Yes Interaction , Google Analytics - Page View |
For store’s checkout | Tracks a user’s journey through the store, from viewing a product to purchasing it. | Google Analytics - Checkout and Order Placed |
Default - For storefront
- In the User-Defined Variables box, click on
New
. - Click on the Variable Configuration box and select Google Analytics Settings.
- Type in your Google Analytics Tracking ID,
{{Analytics Tracking ID}}
. - Go to More Settings > Fields to Set.
- Click the Add Field button. Then, type
location
in Field Name and{{Original Location}}
in the Value field. - Click Add Field. Then, type
referrer
in Field Name and{{Original Referrer}}
in the Value field. - Click Add Field. Then, type
page
in Field Name and{{Page Path}}
in the Value field.
An error occurred while trying to load the image. https://raw.githubusercontent.com/vtexdocs/dev-portal-content/gtm-images-update/docs/vtex-io/Storefront-Guides/google-tag-manager/vtex-io-documentation-setting-up-google-tag-manager-3.webp
- Then, go to Ecommerce and tick the
Enable Enhanced Ecommerce Features
andUse data layer
boxes. - Save your changes as Google Analytics.
If you intend to use the User ID feature of Google Analytics, you need to set a field using the userId
variable previously created.
To do this, click on Fields to set and add the userId
field with its desired value.
For the store's checkout
- In the User-Defined Variables box, click on
New
. - Click on the Variable Configuration box and select Google Analytics Settings.
- Type in your Google Analytics Tracking ID,
{{Analytics Tracking ID}}
. - Go to More Settings > Fields to Set.
- Click the Add Field button. Then, type
location
in Field Name and{{Original Location}}
in the Value field. - Click the Add Field button. Then, type
referrer
in Field Name and{{Original Referrer}}
in the Value field. - Click the Add Field button. Then, type
page
in Field Name and{{Page Path}}
in the Value field. - Then, go to the Ecommerce section and tick the
Enable Enhanced Ecommerce Features
option. - Select the
{{ecommerceV2}}
option in Read data from variable. - Save your changes as Google Analytics - Checkout and Order Placed.
If you have any Google Analytics tags using the Google Analytics Settings variables you have changed, apply the same changes above directly on the tags that need it.
Step 2 - Creating triggers
Triggers are conditions to when you want your tags to fire. For example, if you want to activate the Google Ads conversion tag when a visitor signs up your store newsletter, you use a trigger to do it. To create a trigger, click on Trigger in the left menu and then on New:
An error occurred while trying to load the image. https://raw.githubusercontent.com/vtexdocs/dev-portal-content/gtm-images-update/docs/vtex-io/Storefront-Guides/google-tag-manager/vtex-io-documentation-setting-up-google-tag-manager-4.webp
Custom Events
- Click on the Trigger Configuration box.
- Select Custom Event.
- Type
addToCart
in the Event Name field; - Click on
Save
and save it as Custom Event - addToCart.
Repeat the instructions above, now changing the event name for each of the following event triggers:
cart
email
orderPlaced
payment
productClick
productDetail
productImpression
promotionClick
promoView
profile
removeFromCart
shipping
pageView
To trigger the
promotionClick
event for an image in a store component, you need to include the URL path for that image. To do this, access the CMS > Site Editor and select the image within the component. Then, in the editing view, go to URL and enter the path you want to use, for example,/collections/valentines-70-off
.
Step 3 - Creating Tags
Tags are tracking code you want to implement on your store. For example, if you want to track a page view and send that data to Google Analytics, you use a tag to do it.
To create a tag, click on Tags in the left menu and then on New:
An error occurred while trying to load the image. https://raw.githubusercontent.com/vtexdocs/dev-portal-content/gtm-images-update/docs/vtex-io/Storefront-Guides/google-tag-manager/vtex-io-documentation-setting-up-google-tag-manager-5.webp
Google Analytics - Checkout and Order Placed
- Click on the Tag Configuration box.
- Select Google Analytics - Universal Analytics.
- Choose Event from the Track Type field.
- Type in Ecommerce in the Category field.
- Type in Event in the Action field.
- In Non-Interaction Hit, select
True
- In Google Analytics Settings, select
{{Google Analytics - Checkout and Order Placed}}
. - In the Triggering box, choose the following triggers:
Custom Event - cart
Custom Event - email
Custom Event - orderPlaced
Custom Event - payment
Custom Event - profile
Custom Event - shipping
- Save the new tag as Google Analytics - Checkout and Order Placed.
Google Analytics - Enhanced Ecommerce - No Interaction
- Click on the Tag Configuration box.
- Select Google Analytics - Universal Analytics.
- Choose Event from the Track Type field.
- Type in Ecommerce in the Category field.
- Type in Event in the Action field.
- Select True in the Non-Interaction Hit field.
- In Google Analytics Settings, choose {{Google Analytics}}.
- In the Triggering box, choose the following triggers:
Custom Event - productDetail
Custom Event - productImpression
Custom Event - promoView
- Save the new tag as Google Analytics - Enhanced Ecommerce - No Interaction.
Google Analytics - Enhanced Ecommerce - Yes Interaction
- Click on the Tag Configuration box.
- Select Google Analytics - Universal Analytics.
- Choose Event from the Track Type field.
- Type in Ecommerce in the Category field.
- Type in Event in the Action field.
- Select False in the Non-Interaction Hit field.
- Choose {{Google Analytics}} in the Google Analytics Settings field.
- In the Triggering box, choose the following triggers:
Custom Event - addToCart
Custom Event - removeFromCart
Custom Event - productClick
Custom Event - promotionClick
- Save the new tag as Google Analytics - Enhanced Ecommerce - Yes Interaction.
Google Analytics - Page View
- Click on the Tag Configuration box;
- Select Google Analytics - Universal Analytics.
- Choose Page View from the Track Type field.
- In Google Analytics Settings, select {{Google Analytics}}.
- In the Triggering box, select the Custom Event - pageView trigger.
- Save the new tag as Google Analytics - Page View.
Conversion Linker
- Click on the Tag Configuration box.
- Select Conversion Linker.
- In the Triggering box, choose the All Pages trigger.
- Save the new tag as Conversion Linker.
Google Ads Conversion Tracking
- Click on the Tag Configuration box.
- Choose Google Ads Conversion Tracking.
- Fill in the fields Conversion ID and Conversion Label according to what is instructed by the Google Ads panel.
- Fill in the following fields with Data Layer variables:
- Conversion Value:
{{Data Layer Variable - transactionTotal}}
- Transaction ID:
{{Data Layer Variable - transactionId}}
- Currency Code:
{{Data Layer Variable - currency}}
Remember to replace the values between the curly brackets according to your scenario.
- In the Triggering box, select the Custom Event - orderPlaced trigger.
- Save the new tag as Google Ads Conversion Tracking.
Step 4 - Publishing your changes
Once you have set up the Google Analytics variables, triggers, and tags, follow Google's official guide to submitting and publishing your store’s container.
(Optional) Advanced configurations with Enhanced Ecommerce
To make the product information consistent across all store areas and help capture the entire user's journey on the store, Google Tag Manager 3.x. includes Enhanced Ecommerce properties to the product data schema as events. These properties enable stores to provide additional information, such as product printing, promotion, and sales data.
Prop name | Description |
---|---|
id | Product ID - Previously SKU ID. |
variant | SKU ID - Previously SKU Name. The variant of the product, e.g., Rebel pink. |
name | Product Name - Previously Product Name or SKU Name. |
quantity | Product quantity |
price | Product price. |
category | Product category, e.g., Apparel. |
brand | Product brand. |
dimension1 | Product Reference ID. |
dimension2 | SKU Reference ID. |
dimension3 | SKU Name (does not include the Product Name). |
The dimension1
, dimension2
, dimension3
properties are custom dimensions that you can use to collect and analyze data that Google Analytics does not automatically create.
For more information about custom dimensions and Enhanced Ecommerce, refer to Custom dimensions and metrics and Google Enhanced ecommerce official guide respectively.