[UA to GA4] How gtag.js for Universal Analytics maps to Google Analytics 4

This is an implementation guide for website owners who use the gtag.js library and want to understand how gtag.js for Universal Analytics (UA) maps to Google Analytics 4. It assumes that you have already created a Google Analytics 4 property. If you just need to add the basic measurement code to your website, read this article instead.
In this article:

About the gtag.js snippet and property IDs

The gtag.js snippets for a Universal Analytics property and for a Google Analytics 4 property are fundamentally the same. Both snippets have the following structure:

01: <script async src="https://www.googletagmanager.com/gtag/js?id=<Some Property ID A>"></script>

02: <script>

03: window.dataLayer = window.dataLayer || [];

04: function gtag(){dataLayer.push(arguments);}

05: gtag('js', new Date());

06:

07: gtag('config', '<Some Property ID A>');

08:

09: gtag('config', '<Some Property ID B>');

10:

11: gtag('event', 'sign_up', { 'method': 'email' });

12:

13: gtag('event', 'view_video', { 'send_to': '<Some Property ID B>' });

14:

15: </script>

Line 1: If you have implemented a Universal Analytics property via gtag.js, you will likely already have this line of code on your site. Instead of <Some Property ID A>, you'll see "UA-" followed by a series of numbers. If you have implemented gtag.js for Google Ads or another Google Marketing Platform product, you may also have this line of code on your website, but <Some Property ID A> will begin with "AW-" or "DC-".

The property ID (or Measurement ID, for Google Analytics 4 properties) indicated by <Some Property ID A> "controls" this gtag.js snippet. This is important because:

  1. If this line is already present, it doesn’t need to be implemented a second time. You will only need to add a "config" line to specify the Google Analytics 4 property Measurement ID.
  2. The property ID on this line is the "controller" of the gtag.js snippet. If a Universal Analytics property ID ("UA-XXXXXXXX") controls the tag, you'll be able to use connected site tags to send measurement data to a Google Analytics 4 property, without having to add any new code to the page.

Line 7: The gtag "config" directive enables data collection to the property associated with <Some Property ID A>. For example, in a Google Analytics 4 property, adding this directive with a Measurement ID will send page_view events to that property.

The property ID may represent measurement for different Google products, including a Universal Analytics property ("UA-XXXXXXXX"), a Google Analytics 4 property ("G-XXXXXXXX"), Google Ads ("AW-XXXXXXXX") or Floodlight ("DC-XXXXXXXX").

Line 11: The gtag "event" directive will send an event. In snippets where multiple "config" directives are present for multiple properties, the event will be sent to all properties.

In this example, the "sign_up" parameter is the event name. The last parameter is an object that contains a set of event parameters. In this case, "method" is a parameter with a value of "email."

Line 13: The event here has "send_to" as a parameter. This is a special parameter that sends the associated event to a specific property. In other words, this event will only be sent to the property indicated by <Some Property ID B>.

The gtag "config" directive enables basic measurement.

  • For a Universal Analytics property, the "config" with a Universal Analytics property ID sends a pageview hit.
  • For a Google Analytics 4 property, the "config" with a Google Analytics 4 property Measurement ID enables the collection of page_view events (as an automatically collected event) when it loads on a page.

Property identifiers

Universal Analytics property IDs have the format "UA-XXXXXXXX". This is sometimes referred to as the Tracking ID. In this guide, we'll refer to it as the UA Property ID.

Google Analytics 4 property web data streams use a Measurement ID with the format "G-XXXXXXXX."

In some code examples and documentation, you may see both referred to as "GA_Measurement_ID."

Basic data collection

Enabling basic data collection for a Google Analytics 4 property allows for the following to be collected:

If your existing Universal Analytics property uses a gtag.js implementation, you enable basic data collection for your Google Analytics 4 property by:

  • Option 1: Adding a new "config" directive with the relevant Google Analytics 4 property Measurement ID
    OR
  • Option 2: Turning on connected site tags (if your existing gtag.js implementation is eligible)

Regardless of which option you choose, your existing Universal Analytics property remains unaffected and will continue to collect data.

Option 1: Add a new "config" directive

If there is existing gtag.js code on the page, simply add an additional "config" directive with the relevant Google Analytics 4 property's Measurement ID. In the example below, line 8 has been added to an existing gtag.js implementation. It references the Google Analytics 4 property's Measurement ID. This will send page_view events to that Google Analytics 4 property. It also enables automatically collected events and enhanced measurement events (if you have enabled enhanced measurement) in that Google Analytics 4 property.

1: <script async src="https://www.googletagmanager.com/gtag/js?id=<Some Property ID A>"></script>

2: <script>

3: window.dataLayer = window.dataLayer || [];

4: function gtag(){dataLayer.push(arguments);}

5: gtag('js', new Date());

6:

7: gtag('config', '<Some Property ID A>');

8: gtag('config', 'G-XXXXXXXX');

9: </script>

Option 2: Turn on connected site tags

You can use a connected site tag if:

  • The existing gtag.js snippet on the page where you want to measure user interactions is "controlled" by a Universal Analytics property (i.e., the ID referenced in this line of the gtag.js snippet begins with "UA-"):

<script async src="https://www.googletagmanager.com/gtag/js?id=<Some Property ID A>"></script>

(Connected site tags will also work if the existing gtag.js snippet is controlled by an Google Analytics 4 property. However, you'd only encounter this situation if a Google Analytics 4 property has already been implemented.)

  • AND you have admin access to the Universal Analytics property referenced by the ID in the snippet.
If you have both a gtag.js tag and a GTM container implemented on your page, the gtag.js tag must be placed above the GTM container for connected site tags to work.

Configuration settings for gtag.js

You can configure the basic gtag.js snippet to control data collection settings such as IP anonymization, cookie customizations, and Google Signals. You do this via "config" or "set" directives in gtag.js.

Both Universal Analytics ("UA-XXXXXXXX") and Google Analytics 4 ("G-XXXXXXXX") properties support implementing these config settings via gtag.js. However, there are a few differences between these settings for Universal Analytics and Google Analytics 4 properties. 

  • IP Anonymization is standardized to "true" and not configurable in a Google Analytics 4 property. As such, the IP address is automatically masked with the standard event to Google Analytics 4 property ("G-XXXXXXXX").
  • When global settings need to be applied to all configured properties, the "set" command should be used in order to apply to all Measurement IDs and/or Property IDs, including those implemented via connected site tags.
  • Pay specific attention to Disable Ad Personalization features, which are most typically implemented with a "config" line.
  • When using connected site tags: Any configurations made in the gtag.js code using "config" apply only to the property associated with Measurement ID in that line of code; these will not automatically get sent to the connected Google Analytics 4 property. If you want the configuration to apply to the connected Google Analytics 4 property,
    • Create a separate "config" directive and apply it to the relevant Google Analytics 4 property by referencing the Measurement ID
      OR
    • Configure the setting using a "set" directive, in which case the configuration will be applied to all configured properties.

Configuration examples

Enable basic data collection; configure User-ID

gtag('config', 'GA_MEASUREMENT_ID', {

'user_id': 'USER_ID'

});

Configure cookie settings

gtag('config', 'GA_MEASUREMENT_ID', {

'cookie_prefix': 'MyCookie',

'cookie_domain': 'blog.example.com',

'cookie_expires': 28 * 24 * 60 * 60 // 28 days, in seconds

});

Block a page_view event

If you don't need a page_view event to be sent when you load the config code (for example if you have an iframe loading), you can adjust the config setting to block the page_view event. Consider a scenario in which a page_view event is sent, followed by a user logging in to the site. For the login interaction, you use a "config" directive to set the user ID, but you don't want to send another page_view event. The following code illustrates how to prevent the page_view event from being sent.

gtag('config', 'MEASUREMENT_ID', {

'user_id': 'USER_ID',

'send_page_view': false

});

Events

In a Universal Analytics property implemented via gtag.js ("UA-XXXXXXXX"), events are implemented as a separate hit type, using the dimensions Event Category, Action, and Label and the metric Event Value. When collected, they appear in your reports and there are no limits to the number of different event, dimension and metric values.

In a Google Analytics 4 property, every "hit" is an "event," meaning there is no longer a distinction between hit types.

Types of events in a Google Analytics 4 property

Google Analytics 4 events fall into four categories: automatically collected events, enhanced measurement, recommended events, and custom events.

  1. Automatically collected events are collected automatically with basic data collection.
  2. Enhanced measurement provides events that you can toggle on and off using the Admin interface within a Google Analytics 4 property. Enhanced measurement events DO NOT REQUIRE adding/modifying code on web or in app
    • Note that when events are/remain implemented as individual events and are also collected via enhanced measurement, those events will be logged twice. If you are sending an event to both a Universal Analytics and a Google Analytics 4 property, the solution is to add a "send_to" parameter in the event specifying the relevant Universal Analytics property ID. That way, the event only flows to the Universal Analytics property and not to the Google Analytics 4 property.
    • Technical note: Enhanced measurement is not based on HTML ID’s or classes, unlike situations where you have used HTML ID’s and classes as triggers or variables for events such as link clicks and downloads via Google Tag Manager.

  1. Recommended events are events that you manually implement, but that have Google-predefined names and parameters. Recommended events unlock existing and future reporting capabilities not available for custom events (events that you name yourself). Recommended events exist for:
  1. Custom events are events that you name and implement yourself.

Best practices when implementing events

  1. Wherever possible, use automatically collected and enhanced measurement events instead of implementing events yourself.
  2. If a desired event is not automatically collected and is not provided as part of enhanced measurement, look for a recommended event to implement.
  3. Implement a custom event only if (1) and (2) do not meet your needs.

Make an inventory of all the events that are being used in your Universal Analytics property and see if the automatically collected and enhanced measurement events can cover these needs for your Google Analytics 4 property. Focus on these events first as they do NOT have to be manually coded for migration.

Manually implemented events (i.e., recommended and custom events)

The data structure of events differs between Google Analytics 4 and Universal Analytics properties.

  • In a Universal Analytics property, events have “Event Category”, “ Event Action”, “ Event Label”, and “Event Value” fields and custom dimensions can be added.
  • In a Google Analytics 4 property, a manually implemented event consists of “Event Name”, automatically collected parameters, and manually specified parameters. These manually specified parameters replace the event fields from a Universal Analytics property, and they can also be used for specifying additional information with the event.

If your Universal Analytics property is implemented with gtag.js ("UA-XXXXXXXX") and has not specified a specific "send_to" command, events are automatically translated to a Google Analytics 4 property whenever a Measurement ID ("G-XXXXXXXX") is referenced in the config or if a Connected Site Tag is used.

The translation works as follows:

  • Event Action becomes an Event Name in the Google Analytics 4 property.
  • Event Category, Label, and Value become parameters in the Google Analytics 4 property. Limits on parameters are detailed below.

For example, the following event in a Universal Analytics property implemented via gtag.js:

1: gtag('event', <action>, {

2: 'event_category': <category>,

3: 'event_label': <label>,

4: 'value': <value>

5: });

Is translated to a Google Analytics 4 property using this generalized event signature:

1: gtag('event', <event_name>, {

2: <parameter_1>: <parameter_1_value>,

3: <parameter_2>: <parameter_2_value>,

4: <parameter_3>: <parameter_3_value>,

5: ...

6: });

So, <action> in the Universal Analytics property maps to <event_name> in the Google Analytics 4 property. "event_category", "event_label", "value" and their respective values map to parameters with values.

Naming conventions for manually implemented events

If you use an "Event Name" value that is not one of the automatically collected event names and not one of the Enhanced Measurement event names, your event counts as a manually collected event.

You can use a maximum of 500 different "Event Names." Use recommended event names as much as possible to take advantage of reporting and future capabilities in Google Analytics 4 properties.

Event parameters

Parameters can be used if you want to send information along with an event beyond what is sent by the automatically collected parameters. Any parameters you collect are available for audience definitions and in BigQuery.

Parameter behavior

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 text and 50 numeric parameters per property.

Example

You are measuring clicks on Download links on your website for videos. The tagging structure in a Universal Analytics property can 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 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.

If you have an event structure similar to the example shown above:

  1. Start collecting the data. Review the event data in BigQuery.
  2. Review which of the existing events are already covered by automatically collected events and enhanced measurement. Add a ‘send_to’ command to send these events only to your Universal Analytics property implementation and not to your Google Analytics 4 property.
  3. Implement recommended events wherever possible.

Custom dimensions and metrics

Custom dimensions and metrics can be used to extend information and for importing offline data, e.g., from CRM systems.

When using the global site tag (gtag.js) Custom dimensions and metrics measurements are automatically translated to parameters if connected site tags or a Google Analytics 4 property (e.g., “G-XXXXXXXX”) is used.

Learn more about custom dimensions and metrics.

 

Was this helpful?
How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
Search Help Center
true
69256
false