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
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:
- 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.
- 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.
- Look for a matching recommended event. Implement your tagging to trigger the recommended event.
- 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_purchaseevent on web vsaccess_purchaseevent on app) -
The same events should have the same associated parameters (e.g. avoid passing country for
accessory_purchaseevent on web vs passing country_code foraccessory_purchaseevent on app), and be sure to name the parameters the same (e.g. avoid passing cc parameter foraccessory_purchaseevent on web vs passing country_code parameter foraccessory_purchaseevent 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.
- 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.
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) |
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.
- Disable
page_viewevents 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. - Manually add a
page_viewevent, 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.