Add Google data tags

Google Analytics Enhanced ECommerce

Google Analytics is a free analytics tool that helps you track visitors and conversions on your store. BigCommerce has updated the Google Analytics integration to support Enhanced Ecommerce. As apart of the Enhanced ECommerce feature, Stencil themes now support data attributes.

Data attributes provide detailed data on the way shoppers interact with your store’s products. However, data attributes are not only limited to only product data collection. Data attributes can also track your store’s header and footer for promotions and can collect data on whether those promotions were viewed and/or clicked. BigCommerce’s data attributes are powered by Segment (opens in a new tab) and Platform.js (opens in a new tab), and will send your store’s product data through to Google Analytics.

Cornerstone versions 2.6.0+ will have data attributes already included in the theme.


GAEE for Blueprint Themes

While you can implement data attributes with Blueprint themes, we do not currently have specific documentation on how to do this. The data attribute HTML structure, however, will be the same as it is in a Stencil theme.

Downloading a theme

Data attributes will work on any theme. For this tutorial, we will be adding data attributes to the Cornerstone theme. If you do not already have a local copy of Cornerstone on your machine, see Downloading Cornerstone.

If you would like to implement data attributes on your custom theme and do not already have a copy of your custom theme downloaded, see Downloading a Marketplace Theme.

The remainder of this tutorial will be working off the theme’s base folder cornerstone.

Adding data attributes


Include the Enhanced ECommerce property

  1. Open your local copy of your theme and navigate to the theme’s cornerstone/config.json file.

  2. In the config.json file, navigate to the features array. There should be a property in this array called enhanced ecommerce. If the enhanced ecommerce property is not present in the features array, add it. The features object should then look similar to the image below.

Enhanced eCommerce feature: config.json
"features": [

You are now ready to begin adding data attributes into the HTML files across your Cornerstone theme.

Adding data attributes into Cornerstone’s HTML files

Data attributes must be manually added to a product in order to track shopper events and interactions with a product. Because data attributes collect product data at a very granular level, there will be multiple locations you will have to add attributes on a singular product in order to get a comprehensive look at the product’s data. For example, if you want to, it is imperative to note that a product can be viewed by clicking any of the following:

  • The name of the product
  • The “Quick View” button
  • The product image

So, if you would like to track the clicks on a specific product, in order to ensure you get a fully comprehensive look at shoppers’ interactions with a product, you will want to include a data attribute on each of these fields. If a specific product possesses multiple data attributes, the data attribute that is closest to the product is the one which will track clicks, product impressions, or product views.

Data attributes will be implemented in your store by using simple HTML. In order to begin tracking, you will add data attributes to the already existing HTML tags present in your theme.

See Pull Request #1377 (opens in a new tab) to see how data attributes were implemented in Cornerstone 2.6.0.

Data attribute implementation example

You can see a data attribute implemented in the HTML form tag in the code sample below:

Data attribute HTML
<form action="{{}}" method='POST' data-list-name="Brand: {{}}" data-product-compare>
    {{#if theme_settings.product_list_display_mode '===' 'grid'}}
        {{> components/products/grid products=brand.products show_compare=brand.show_compare theme_settings=theme_settings event="list"}}
        {{> components/products/list products=brand.products show_compare=brand.show_compare theme_settings=theme_settings event="list"}}
{{> components/common/paginator pagination.brand}}

In the above snippet, the data attribute is embedded in a <form> HTML tag in lines 1 and 2. The data attribute is data-list-name and its value is "Brand: {{}}".

Data attribute reference

Currently, BigCommerce supports 11 different data attributes. Below is a table with a breakdown of each attribute and its description.


Mandatory data

  • If tracking promotions data, either data-banner-id or data-name are required.
  • If tracking data for a product, either data-entity-id or data-name are required.
  • If tracking data for a product list, data-product-list or data-entity-id are required.

The “tracked product” refers to the product on which you are inserting the data attribute.

Data AttributeDescriptionValue TypeExample
data-list-nameThe data-list-name attribute denotes the name of the list that will be reflected on Google Analytics.string or handlebars helperString Example:data-list-name="Kitchen Appliances"

Handlebars Value Example: The data-list-name attribute can also get its value using Handlebars. For example, if you are adding a data attribute to your carousel products in products/carousel.html, you could create the attribute data-list-name="{{list}}" and define the list value in products/new.html to be: list="New products"
data-entity-idThe data-entity-id is equal to the tracked item’s id.integerdata-entity-id=12
data-positionThe data-position attribute is equal to the tracked product’s position or the tracked promotion’s position.Value is a string if creating the data attribute for a promotion. The string should denote the location of the promotion.

Value is an integer if creating the data attribute for a product. The integer should represent the product’s placement. An example use case for this data attribute is to answer a question like, “does the product in position 1 sell more than the product in position 4?”
String Value Example: data-position="center"

Integer Value Example: data-position=2
data-banner-idThe data-banner-id attribute is the id of the banner being tracked. The banner id is not to be mistaken with the promotion id.integerdata-banner-id=5
data-event-typeThe data-event-type attribute is equal to the shopper event that will be tracked. There are a 4 shopper/product interactions you can measure and set the data-event-type equal to. Custom events are not yet implemented.String that can be one of:
"promotion click"
data-nameThe data-name attribute is equal to the tracked product’s or banner’s name.string or handlebars helperString Value Example:
data-name="Ruffle Off-the-Shoulder Top"

Handlebars Value Example:
The data-name attribute can also get its value using Handlebars.

For example, if you are adding a data attribute to your footer in products/footer.html, you could create the attribute: data-name="{{this.banner-name}}"

Or, if you are adding a data attribute to a product list item in products/list-item.html, you could create the attribute below data-name="{{name}}" as long as these values are defined.
data-product-categoryThe data-product-category attribute is equal to the tracked product’s category.stringdata-product-category="Women’s Apparel"
data-product-brandThe data-product-brand attribute is equal to the tracked product’s brand.stringdata-product-brand="Ralph Lauren Corporation"
data-product-priceThe data-product-price attribute is equal to the tracked product’s price.integerdata-product-price="27.99"
data-product-skuThe data-product-sku attribute is equal to the tracked product’s sku value.stringdata-product-sku="S18T-Ots-YM"
data-product-variantThe data-product-variant is equal to the tracked product’s variant.stringdata-product-variant="4-Yellow"

Custom Dimensions and Metrics

Custom dimensions and metrics are also supported. To add them in the config.json settings array, add the name of the dimension/metric followed by the generic custom metric/dimension alias:

config.json: Settings array
    // ...
    "settings": {
        // ...
        "custom-dimensions": {
            "<your-custom-dimension-name>": "dimension1", "dimension-common": "dimension2"
        "custom-metrics": {
            "<your-custom-metric-name": "metric1", "metric-common": "metric2"
    // ...
  • Spelling must be exact
  • Names may not have spaces

Next, add the custom metrics/dimensions to the desired theme template:

Theme template with custom dimensions and metrics
{{#if settings.data_tag_enabled}}
    <article class="listItem" dimension-common="yes" metric-common=1 data-event-type="{{event}}">

Dimensions and metrics

Dimensions are typically strings; metrics are usually integers.


Pull Requests

Related Articles

Additional Resources

Did you find what you were looking for?