[UA→GA4] Map Universal Analytics events and custom dimensions to Google Analytics 4

As outlined in the article Events in Google Analytic 4 vs Universal Analytics, an essential task in migrating from Universal Analytics to Google Analytics 4 is the translation of your current measurement approach — including pageviews, events, custom dimensions, and sometimes custom metrics — into the Google Analytics 4 schema.

While migrating to a different measurement paradigm provides the opportunity to reevaluate your overall approach to measurement, realign with stakeholders, and develop new requirements and KPIs, these articles focus on replicating in Google Analytics 4 the aspects of your Universal Analytics measurement that are essential.

In this article:

• Map events
• Map custom dimensions

Map events

The paradigm of automatically collected and recommended events does not pertain to Universal Analytics, but it does form the core of Google Analytics 4 implementations.

When mapping events from a Universal Analytics property to a Google Analytics 4 property:

1. First, look for matching enhanced measurement event.
   • If you find a matching event, you should not recreate a new event. 
   • Add the 'send_to' parameter to send the events only to your Universal Analytics property implementation and not to your Google Analytics 4 property. Learn more about event routing.
   • If no matching enhanced measurement event exists, proceed to step 2.
2. Look for a matching automatically-collected event.
   • If you find a matching event, you should not recreate a new event.
   • Add the 'send_to' parameter to send the event only to your Universal Analytics property implementation and not to your Google Analytics 4 property.  Learn more about event routing.
   • If no matching automatically-collected event exists, proceed to step 3.
3. Look for a matching recommended event. Implement your tagging to trigger the recommended event.
4. Finally, if you cannot find a suitable equivalent event, create your own custom event.

 

The following table provides examples of events implemented in Universal Analytics and how you could replicate them in Google Analytics 4.

UA event definition	GA4 event type	GA4 event configuration
Event Category: download Event Action: pdf Event Label: catalog.pdf	automatically collected event	The file_download event, and associated parameters such as file_name, that are recorded by default as part of enhanced measurement in a web data stream serve the same purpose. You don’t need to manually recreate this event in Google Analytics 4.
Event Category: engagement Event Action: login Event Label: google-sso	recommended event	Use the recommended login event with the recommended method parameter set to google-sso.
Event Category: navigation-click Event Action: top Event Label: company-about-us	custom event	Since there is no equivalent automatically collected or recommended event in Google Analytics 4, you can use your own naming for a custom event and parameters. For example, navigation_click as the event name and click_location=top and click_text=company-about-us as custom parameters.

Recommended events vs. custom events

The recommended events in Google Analytics 4 are similar to custom events in that they’re not tracked automatically and you have to manually add them to your measurement code and specify the event names and other parameter values.

The significance of recommended events is that they are (or may be in future product updates) treated differently in the reporting interface. For example, Google Analytics 4 looks specifically for the recommended online sales events and parameters to populate the built-in Monetization reports. If you use different values to record website or mobile-app ecommerce actions, you’ll need to create your own custom reports to read the data that you have recorded — your data will not populate the built-in Monetization reports.

Not all recommended events currently populate specific built-in reports, but implementing recommended events lets you automatically populate new reports that become available in the future.

Align app and web events

Google Analytics 4 properties combine app and web measurement; in contrast, Universal Analytics properties are web-focused. If you have an app data stream in your Google Analytics 4 property and are looking for cross-platform insights, you should ensure that your event data collection is consistent across app and web.

For example, here are a few things to watch for:

• The same events should be named the same (e.g. avoid accessory_purchase event on web vs access_purchase event on app)

• The same events should have the same associated parameters (e.g. avoid passing country for accessory_purchase event on web vs passing country_code for accessory_purchase event on app), and be sure to name the parameters the same (e.g. avoid passing cc parameter for accessory_purchase event on web vs passing country_code parameter for accessory_purchase event on app)

• The same parameters should have comparable values passed during data collection. (e.g. avoid passing US for country_code parameter on web vs passing USA for country_code parameter on app)

• The values passed for User ID are of the same type across app and web (e.g. avoid the string '555321' on web vs the integer 555321 on app)

Consistent implementation and event naming ensures that your app and web data are comparable and that you're able to see an accurate picture of the user journey.

Event naming and parameter considerations

Use recommended event names as much as possible to take advantage of reporting and future capabilities in Google Analytics 4 properties.

Use event parameters to send information along with an event beyond what is sent by the automatically collected parameters (language, page_location, page_referrer, page_title, screen_resolution). Any parameters you collect are available for audience definitions and in BigQuery.

A parameter can contain an unlimited number of unique values. However, there are important limitations and behaviors that need to be taken into account when setting up a Google Analytics 4 property alongside a Universal Analytics property.

Note:

• You can send a maximum of 25 custom parameters per event, and each parameter value can be 100 characters long.
• There is a total limit of 50 custom dimensions and 50 custom metrics per property.

Example

 

You are measuring clicks on download links on your website for videos. The tagging structure in a Universal Analytics property may look like this:

 

event_category: "Videos"

action: "Download"

event_label: "Toy Story"

If the Universal Analytics property was implemented via gtag.js, this event will be translated in a Google Analytics 4 property according to the following logic:

• "Download" becomes the event name
• "event_category" becomes a custom parameter
• "event_label" becomes a custom parameter

A more generalized event structure would then look like this:

event_category: [resourceType]

action: [interactionType]

event_label: [resourceName]

In a gtag.js implementation, the action becomes the event name; if you have 10 types of interactions, this will translate into 10 different event names.

Translating parameters from a Universal Analytics property to a Google Analytics 4 property follows a similar format; you would have event_category and event_label parameters added to each new action event.

Map custom dimensions

Custom dimensions provide the critical functionality for extending the Google Analytics dataset to capture taxonomies about your pages, events, and users that are most relevant to you.

The concept of custom dimensions in Google Analytics 4 is similar to the equivalent in Universal Analytics, but with broader capabilities. In Google Analytics 4, you probably want to maintain the custom dimensions that you defined in Universal Analytics. Additionally, many of the values that you tracked as event dimensions in Universal Analytics, particularly event category and event label, should be recreated in Google Analytics 4 as custom dimensions.

Learn more about how to create custom dimensions and metrics.

Google Analytics 4 previously had the concept of registering custom event parameters so that they would appear in reports. That concept no longer applies — you now achieve the same effect by simply creating custom dimensions and metrics.

The table below illustrates how you could map Universal Analytics event measurement to Google Analytics 4.

Use Case	Universal Analytics	GA4 - auto collected or custom event	GA4 - custom dimension or metric
Measure video engagement	Event Action = video_start	Turn on "Video engagement" in enhanced measurement.	If you want visibility into video progress, create a custom dimension based on video_percent
	Event Category = engagement
	Event Label = lesson-1		Create a custom dimension based on video_title
Record loan calculator interactions	Event Action = loan-calculator	Event name: loan_calculator (custom)
	Event Category = refinance	Event parameter: loan_type = refinance (custom)	Create a custom dimension based on this event parameter
	Event Label = residential	Event parameter: borrower_type = residential (custom)	Create a custom dimension based on this event parameter
	Current Borrower (custom dimension) = true	Event parameter: current_borrower = true (custom)	Create a custom dimension based on this event parameter
	Loan Amount (custom metric) = 250000	Event parameter: loan_amount = 250000 (custom)	Create a custom metric based on this event parameter *
Record author and category for blog pages	pageview hit	Event name: page_view (custom) **	**
	Author (custom dimension) = theresa c.	Event parameter: author = theresa c (custom)	Create a custom dimension based on this event parameter
	Blog Category (custom dimension) = privacy-legislation	Event parameter: blog_category = privacy-legislation (custom)	Create a custom dimension based on this event parameter
Record loyalty level when a user logs in	Event Action = login	Event name: login (recommended)
	Event Category = login ***
	Loyalty Level (custom dimension) = platinum	Event parameter: loyalty_level = platinum (custom)	Create a custom dimension based on this event parameter (user-scope)

Notes:

 

* In addition to or instead of the custom metric, you could create a custom dimension. This would allow you to display the event count and other metrics for loan calculations at different loan amounts.

 

** See Pass custom parameters for pageviews below.

 

*** Event Category and Event Action are required for event tracking in Universal Analytics, even if a single descriptor would suffice. An additional benefit of Google Analytics 4’s flexible event model is the option to populate only an event name (and no requirement to add any parameters) to describe the user interaction.

Pass custom parameters for pageviews

One of the examples in the table above identifies author and blog_category as custom parameters that you might want to include with Google Analytics 4 pageviews. Since you can’t add custom parameters to the automatic pageviews enabled in enhanced measurement, you can take one of the following two approaches.

Option 1: Disable automatic pageview tracking and send a customized pageview event.

1. Disable page_view events by setting send_page_view: false when you use the Google tag (gtag.js) or by modifying the GA4 Configuration tag by clearing the "Send a page view event when this configuration loads" checkbox when you use Tag Manager.
2. Manually add a page_view event, passing in additional custom parameters.
   This approach may be especially suitable if you need to add custom parameters to most of your pageviews.

Option 2: Send a custom event specifically to capture additional parameters

You can also use a custom event to capture additional parameters. For example, you can create a custom event called record_page_metadata that records only the author and category on a page. For mobile apps, you can add custom parameters to manually tracked screenviews. For example, you can create a custom event called screen_view_duplicate with a custom parameter page_topic=education-opportunities.

Note: Sending duplicate events increases the total number of events captured at a given time, which could trigger sampling within shorter date ranges or at smaller sample sizes.

This approach may be best when you want to record custom parameters for a small portion of pageviews or screenviews, or when you don't expect to approach the sampling limit.

Custom dimensions for automatically collected and recommended parameters

Some event parameters that are captured automatically in Google Analytics 4 are mapped to built-in reporting dimensions: page_title is one example. Many other automatically collected and recommended parameters, such as file_name in the file_download event example above, are not automatically mapped to either built-in or custom dimensions or metrics; you still need to map these parameters to custom definitions before using them for most reporting purposes in Google Analytics 4.