GA4 ecommerce (Tag Manager): Send GA4 events

This guide describes how to update an existing Universal Analytics (Tag Manager) ecommerce implementation to use Google Analytics 4 ecommerce events.

Visit the Developer migration center for additional migration guides and resources.

Outcome

The outcome of following this guide is that your existing Universal Analytics implementation will be updated to use GA4 ecommerce events and parameters. This updated ecommerce implementation will also be used to send ecommerce data to a new GA4 property. Your UA ecommerce reports will continue to be populated with data and you will begin receiving data in your new Google Analytics 4 property.

Caution: Although Google Analytics 4 ecommerce events are automatically translated to be compatible with Universal Analytics, not all Google Analytics 4 events have an equivalent event in Universal Analytics. Data will be missing in Universal Analytics ecommerce reports for these events. See Trade-offs and considerations below.

Before you begin

1. Use the ecommerce migration helper tool to confirm that the following describes your current implementation:

   • You are using a Universal Analytics property
   • Your site uses Tag Manager and is using the data layer to send ecommerce events

2. Review the migration options for ecommerce implementations to learn about the trade-offs of each option. Confirm that you do indeed want to follow this guide to use Google Analytics 4 ecommerce events for your existing Universal Analytics implementation.

3. Review the Event compatibility reference to learn how UA events are translated when sent to a GA4 property.

Trade-offs and considerations

Review and consider the information below to fully understand the implications of using Google Analytics 4 ecommerce events with your existing Universal Analytics (Tag Manager) ecommerce implementation.

Pros	Cons
Allows you to see ecommerce data in both your GA4 and Universal Analytics reports. Using GA4 events and parameters ensures complete GA4 ecommerce reports.	Requires you to change your existing ecommerce events. Not all GA4 events and parameters have equivalents in Universal Analytics. The shipping_tier, discount, currency, location_id, promotion_name, and promotion_id parameters have no Universal Analytics equivalents and will not appear in your Universal Analytics reports.

Implementation

A key implementation objective is to transition from using the data layer to using the gtag.js API. To make sure there are no measurement interruptions while making this transition, the instructions below recommend that all tag configuration updates are completed first, followed by updates to the data layer.

1. Create and configure a new GA4 property

Complete the following steps to create and configure your new Google Analytics 4 property:

1. Create a new Google Analytics 4 property.
   • Use the GA4 Setup Assistant to automatically create a new GA4 property and copy the following settings from your Universal Analytics property: property name, website URL, timezone, and currency settings. However, uncheck the Enable data collection using your existing tags option to disable the connected site tag feature. Alternatively, if you don't want to copy any settings from your Universal Analytics property create a Google Analytics 4 property without the GA4 Setup Assistant.
2. Add the Google tag.
   1. Open the Google Tag Manager container for your existing Universal Analytics implementation.
   2. Click Tags > New.
   3. Click Tag Configuration and select Google Tag.
   4. Enter the tag ID of your Google Analytics 4 property.
   5. Select to trigger the tag on All Pages (or on the subset of pages you want to measure).
   6. Save and publish your tag configuration.

2. Add a GA4 Event tag configuration to measure ecommerce events

Complete the following steps to add a GA4 Event tag to send ecommerce events and parameters to your GA4 property:

1. Create a new Tag Configuration and select GA4 Event.
2. For Event Name use the built-in variable {{Event}}. This will use the GA4 ecommerce event name sent using the gtag.js API.
3. Under More Settings and then Ecommerce, check Send Ecommerce data.
4. For Data Source select Data Layer.
5. Click Save. Triggers will be added in later steps so you can safely ignore any warnings about missing triggers.

Key Point: You do not need to create multiple GA4 Event tags. Instead, a single GA4 Event tag using the built-in Event variable can be used for all ecommerce events. The tag triggers will define the specific GA4 ecommerce events that fire the tag.

3. Update your UA ecommerce tag configurations to use GA4 events

For each Universal Analytics ecommerce tag configuration you will need to add a trigger to fire on the equivalent GA4 ecommerce event and enable the option to read GA4 ecommerce event data.

For each Universal Analytics ecommerce event, the general steps to update to a corresponding GA4 event are as follows:

1. For the UA ecommerce event you intend to update, use the information available in the Compatibility between UA and GA4 events and Comparable parameters for UA and GA4 tables and/or the ecommerce migration helper to identify the corresponding GA4 event name. For example, if you're updating an event to measure product clicks, the GA4 event name would be select_item.
2. Update the Universal Analytics Tag Configuration for the event:
   1. Under More Settings and then Ecommerce, check Use GA4 schema to make sure your existing tags correctly read the updated GA4 ecommerce event. It's OK to make this change prior to migrating from the data layer to the gtag.js API.
   2. In the Triggering section, add a new Custom Event trigger, where the Event Name is the GA4 ecommerce event identified above. After completing this step you should have at least 2 triggers: the original trigger that fired the tag and the newly added trigger that will eventually fire once you complete the transition to GA4 events. The additional trigger is to ensure there is no data interruption when transitioning from the data layer to the gtag.js API, as described later in this document.
   3. Save the changes.
3. Add the new trigger to the GA4 Event tag:
   1. Open the GA4 Event tag that you previously configured to send ecommerce events and parameters to your GA4 property.
   2. In the Triggering section, add the Custom Event trigger created above (e.g. select_item) to ensure the GA4 event tag will fire for the associated ecommerce activity after you transition to GA4 events.
   3. Save the changes.
4. Repeat the steps above for each Universal Analytics ecommerce activity. Publish your changes in Tag Manager when complete.

Caution: Make sure to enable the Use GA4 schema option in your Universal Analytics tag configuration. If this option is not enabled your UA ecommerce reports will not populate correctly.

4. Enable the gtag.js API

To update your ecommerce implementation from UA to GA4, it's recommended you transition from using the data layer to using the gtag.js API, which works in coordination with Tag Manager.

To enable the gtag.js API add the following snippet of code to the top of your page above your Tag Manager container snippet:

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
</script>

Caution: If you previously followed Adding Data Layer Variables to a Page and have already declared a data layer variable on the page, the snippet above should be placed after your existing data layer declaration.

5. Transition from using the data layer to using gtag.js

Once you've completed all tag configuration updates and have enabled the gtag.js API, you are ready to transition from using the data layer to using the gtag.js API.

To assist with the update, use the following resources:

• The Ecommerce (GA4) Developer Guide to learn how to send GA4 ecommerce events using the gtag.js API and configure the GA4 Event tag and triggers in Tag Manager.
• The Compatibility between UA and GA4 events table to help you find the appropriate GA4 event name for a Universal Analytics ecommerce activity. For example, if you're updating an event to measure product impressions, the GA4 event name would be view_item_list.
• The Comparable parameters for UA and GA4 table to help you map UA ecommerce parameter names to equivalent GA4 ecommerce parameter names.
• The ecommerce migration helper to validate you have updated your ecommerce events correctly.

For each Universal Analytics ecommerce event, the general steps to transition from using the dataLayer.push() API with UA Ecommerce events to using the gtag.js API with the corresponding GA4 ecommerce event are as follows:

1. Update custom event names with the corresponding GA4 event name. For example, if you're updating an event to measure a product click which uses a custom event name of productClick, the updated event name for GA4 would be select_item. The GA4 event name must match the event name of a trigger you configured earlier.

   For example, the following product click event using the data layer

   dataLayer.push({'event': 'productClick', 'ecommerce': {<ecommerce_parameters>}});
   

   becomes the following when transitioned to the gtag.js API:

   gtag('event', 'select_item', {<ecommerce_parameters>});
   

2. Update the ecommerce parameters to match what's expected for the GA4 event. Make sure to use Comparable parameters for UA and GA4 since there have been parameter name changes. Populate the GA4 parameter value with the matching UA parameter value.

Note: Once the migration from using the dataLayer.push() API to the gtag.js API is complete, you can optionally remove any custom event triggers that fire based on old UA data layer events.

Example: Update a UA event to GA4

The following example shows how to create an equivalent GA4 Event for a product click ecommerce activity implemented in Tag Manager for Universal Analytics.

Before: Sending UA events using the data layer

The following Measures a Product Click for Universal Analytics, implemented using the data layer. The custom event name is productClick.

<script>
/**
 * Call this function when a user clicks on a product link. This function uses the event
 * callback datalayer variable to handle navigation after the ecommerce data has been sent
 * to Google Analytics.
 * @param {Object} productObj An object representing a product.
 */
function(productObj) {
  dataLayer.push({
    'event': 'productClick',
    'ecommerce': {
      'click': {
        'actionField': {'list': 'Search Results'},      // Optional list property.
        'products': [{
          'name': productObj.name,                      // Name or ID is required.
          'id': productObj.id,
          'price': productObj.price,
          'brand': productObj.brand,
          'category': productObj.cat,
          'variant': productObj.variant,
          'position': productObj.position
         }]
       }
     },
     'eventCallback': function() {
       document.location = productObj.url
     }
  });
}
</script>

In Tag Manager, the Universal Analytics tag configuration is as follows:

Tag type : Universal Analytics
Track type : Event
Event Category: Ecommerce
Event Action: Product Click
Enable Enhanced Ecommerce Features: true
Use Data Layer: true
Trigger: event equals productClick

The trigger configuration is set to fire the tag when the productClick event is pushed to the data layer:

After: Sending GA4 Events using gtag.js

Tag configuration updates for UA

In Tag Manager, the Universal Analytics tag configuration is updated for the product click event to trigger on the GA4 event name and the Use GA4 schema option is enabled. The tag configuration is now as follows:

Tag type : Universal Analytics
Track type : Event
Event Category: Ecommerce
Event Action: Product Click
Enable Enhanced Ecommerce Features: true
Use Data Layer: true
Use GA4 schema: true
Trigger #1: event equals productClick
Trigger #2: event equals select_item

The trigger configuration of the new Custom Event trigger is set to fire the tag on the select_item Event name:

Tag configuration updates for GA4

A GA4 Event is configured to measure ecommerce activities implemented using GA4 events and parameters. The tag uses the built-in Event variable to pass along the event name to GA4. The same trigger created for the UA tag (i.e. select_item) is used to fire the GA4 tag.

Transition from using the data layer to using gtag.js

The following shows how the UA implementation above is transitioned from using the productClick custom event with the dataLayer.push() API to using the GA4 select_item event with the gtag.js API. The parameter values for select_item are set accordingly.

<script>
/**
 * Call this function when a user clicks on a product link.
 * @param {Object} productObj An object representing a product.
 */
function(productObj) {
  gtag('event', 'select_item', {
    'items': [{
      'item_id': productObj.id,
      'item_name': productObj.name,
      'index': productObj.position,
      'item_list_name': 'Search Results',
      'item_brand': productObj.brand,
      'item_category': productObj.cat,
      'item_variant': productObj.variant,
      'price': productObj.price
    }]
  });
}
</script>