Ecommerce migration helper

To run an analysis, select which library your current implementation uses and provide an ecommerce event snippet to analyze. For detailed instructions see How to use the tool.

1. Which library does your current ecommerce implementation use?

Tag Manager - dataLayer.push(...); gtag.js - gtag('event', ...);

2. Provide an ecommerce event to analyze.

Replace the default example below with the ecommerce event data you want to analyze and click Analyze. The event data should be copied from your existing ecommerce implementation. For additional help see How to use the tool.

Identification

Validation

Recommended GA4 event

To send your event above as a GA4 event use the following command:

Purpose of the tool

To simplify the transition from Universal Analytics to Google Analytics 4, ecommerce events and parameters for UA and GA4 are compatible in most, but not all, cases. Review the guides available on the GA4 upgrade center for details on compatibility and the pros/cons of various upgrade options.

The ecommerce migration helper can be used to clarify the compatibility of an event with various library/API and tag configurations. It helps with the following:

1. Identify which version and API/library is used to send the ecommerce event to Google Analytics.
   • It will attempt to identify whether the event is Universal Analytics, or Google Analytics 4 and which tagging solution was used.
   • Why?: Identify your current implementation, if you're not sure.
2. Validate how your implementation is interpreted by Google Analytics tags in Google Tag Manager.
   • How the event is interpreted by various tag configurations. For example, if the event you provide is a UA purchase event sent using the Data Layer the tool can show how that event and associated parameters map to the equivalent GA4 event.
   • Why? (1) confirm your ecommerce events are well-formed and (2) understand how data maps to equivalent parameters (or doesn't) when sending GA4 events to a UA property or sending UA events to GA4 property.
3. Recommend how to transition the event to an equivalent GA4 event.
   • Why? To assist with transitioning the your implementation to the recommended GA4 format.

How to use the tool

Enter details about your current implementation

Configure the tool by selecting which library/API you're using to send ecommerce data and provide the details of the ecommerce event you want to analyze. Note: The tool is preconfigured with a default example for both the dataLayer.push API and gtag API cases.

• Tag Manager - dataLayer.push(...);
  • The default example is a GA4 purchase ecommerce event sent to Google Analytics using the Data Layer update method. For comparison, see a similar GA4 purchase example snippet.
  • In the Data Layer update input field, provide the ecommerce event object to analyze. Only include the key/value pairs and not the dataLayer.push method call. All objects must include an event key. If your implementation does not have an event key because the event is triggered automatically (e.g. DOM load) then you'll need to add an event key to use the tool.
    • The GA4 recommendation result will not work if you use custom event names. Instead use the recommended GA4 event name for the corresponding ecommerce action. See UA ecommerce activities and equivalent GA4 Event names to determine the correct event name. For example, a product click event using a custom event name of productClick would need to be updated from:
      {'event': 'productClick', 'ecommerce': {...}}
      to:
      {'event': 'select_item', 'ecommerce': {...}}
• gtag.js - gtag('event', ...);
  • The default example is a GA4 purchase ecommerce event sent to Google Analytics using the gtag.js API. For comparison, see a similar GA4 purchase example snippet.
  • Event name and parameters are entered separately in the Event name and Event parameters input fields, respectively. For ecommerce parameters, only provide the ecommerce object and not the gtag() function call.

Results of analysis

The Identification section attempts to identify the library/API used to send the ecommerce data and the Google Analytics version for which the data is formatted.

The Validation section shows how the event is interpreted for various Google Analytics configurations.

The Recommended GA4 event section attempts to generate the corresponding GA4 event for the provided event.

Example

Analyze the default gtag.js example, a purchase event using the gtag API, the results are as follows:

• Identification: The example uses the gtag API and the GA4 ecommerce data format.
• Validation:
  • Google Analytics 4 and Universal Analytics (GA4 support enabled) configurations both read the ecommerce data as shown in the analysis results. The Universal Analytics tag without GA4 support enabled will not read the ecommerce data sent and the No ecommerce data found message is shown.
• Recommendation: The command to send the event using the gtag API is shown. Since the default event uses the gtag API to send a GA4 event, there is no difference.

To view open issues, send feedback or report an issue, see ecommerce-migration-helper.