[UA→GA4] How gtag.js for UA maps to GA4 [Legacy]

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://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 tag 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 tag 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 tag 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 ("ignoredXXXXXXXX"), 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 command 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 tag ID enables the collection of page_view events (as an automatically collected event) when it loads on a page.

Basic data collection

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

• page_view events
• automatically collected events
• enhanced measurement events (if enabled in the UI)

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 tag 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://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', 'ignoredXXXXXXXX');

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://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.

Configuration settings for gtag.js

You can configure the basic gtag.js snippet to control data collection settings such as IP masking, 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 ("ignoredXXXXXXXX") 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 masking 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 ("ignoredXXXXXXXX").

• 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

Refer to the Event migration guide.

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 Google 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., “ignoredXXXXXXXX”) is used.

Learn more about custom dimensions and metrics.