Set up the Analytics tag

Add the Analytics tag to your website to begin seeing data in your property.

Before you begin

This article assumes that you have already set up a property for your website.

Steps

  1. Find your page tag.
  2. Tag your website.

You can then use the Realtime report to verify that you're receiving data.

Find your page tag (and "G-" or "UA-" ID)

  1. Sign in to Analytics.
  2. Click Admin.
  3. In the Account column, check that you have the desired account selected (directly below the "+Create Account" button at the top). 
  4. In the Property column, check that you have the desired property selected, then click Data Streams, then Web. Click the data stream.
    Your “G-” ID appears in the upper right portion of the panel. Your global site tag appears under Tagging Instructions.
    Don't see a Data Streams option in the Property column? You have a Universal Analytics property. In the Property column, click Tracking Info then Tracking Code. Your “UA-” ID appears in the upper left portion of the panel. Your global site tag appears under Website Tracking.

Tag your website

Add your tag to a website builder or CMS-hosted website (for example, WordPress, Shopify, etc.)

You'll need to add the Analytics tag to your website to begin seeing data in the property you created.

  1. Click Admin.
  2. In the Account column, check that you have the desired account selected (directly below the "+Create Account" button at the top). 
  3. In the Property column, check that you have the desired property selected, then click Data Streams, then Web. Click the data stream.
  4. Under Tagging Instructions, click Add new on-page tag and look for "Global Site Tag (gtag.js)". Your Analytics page tag is the entire section of code that appears, beginning with:
    <!-- Global Site Tag (gtag.js) - Google Analytics -->
    and ending with
    </script>

Copy and paste your entire Google Analytics page tag to your website using your CMS' custom HTML feature. Follow your CMS' instructions on how to do this below:

You can then use the Realtime report to verify that you're receiving data.

Add gtag.js directly to your web pages

You'll need to add the Analytics tag to your website to begin seeing data in the property you created.

  1. Click Admin.
  2. In the Account column, check that you have the desired account selected (directly below the "+Create Account" button at the top). 
  3. In the Property column, check that you have the desired property selected, then click Data Streams, then Web. Click the data stream.
  4. Under Tagging Instructions, click Add new on-page tag and look for "Global Site Tag (gtag.js)". Your Analytics page tag is the entire section of code that appears, beginning with:
    <!-- Global Site Tag (gtag.js) - Google Analytics -->
    and ending with
    </script>
  5. Copy and paste your entire Analytics page tag immediately after the <head> on each page of your website.

You can then use the Realtime report to verify that you're receiving data.

Implementation guide (if you have have advanced instrumentation needs or you are upgrading from Universal Analytics)

If you want to understand how gtag.js for a Universal Analytics (UA) property maps to a Google Analytics 4 property and want in-depth implementation guidance, read the sections below.

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 "routes" 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>.

Regardless of whether you are implementing a Google Analytics 4 property or a Universal Analytics property, 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."

Enable basic data collection

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

In this guide, "basic data collection" means enabling these three sets of events. "Advanced implementation" refers to manually implementing specific events.

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.

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. Note the following considerations.

  • 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

});

Advanced implementation

Basic data collection provides rich measurement capabilities via page_view events, automatically collected events and enhanced measurement. However, you may have additional instrumentation for your Universal Analytics property that needs to be translated over to the new Google Analytics 4 property.

Event tagging

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. See below under "Limits for event collection" for more details.
  • 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: "Gone With the Wind"

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. In a Universal Analytics property ("UA-XXXXXXXX" ), custom dimensions and metrics need to be created in the user interface, are assigned an ID, and can then be implemented or imported. They can be created with 4 different scopes: hit, session, user, product.

In a Google Analytics 4 property ("G-XXXXXXXX"), the custom dimensions and metrics use case is implemented in a different way. Custom dimensions and metrics measurements with gtag.js are automatically translated to parameters if Connected Site Tags or a Google Analytics 4 property “G-XXXXXXXX” is used.

A custom dimension for a Universal Analytics property may be implemented via gtag.js as follows:

1: gtag('config', 'GA_MEASUREMENT_ID', {

2: 'custom_map': {'dimension<Index>': 'dimension_name'}

3: });

4:

5: gtag('event', 'event_name', {'dimension_name': dimension_value});

Line 2: A custom dimension registered via the user interface is associated with an index. That index is associated with a dimension name via a custom map.

Line 5: The dimension name is specified as part of a gtag "event" directive with an associated value.

Custom maps are not supported in Google Analytics 4 properties. The dimension name and dimension value specified in the "event" directive follow the familiar gtag.js 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: });

Consequently, dimension names from a Universal Analytics property implemented via gtag.js are translated into parameters in a Google Analytics 4 property.

There are two caveats:

  1. Parameters need to be registered in the user interface to appear in reports. This is a comparable process to registering custom dimensions in Universal Analytics (limits apply). You don't need to register them if you are only looking at exported data or only use the parameter for audience activation.
  2. The scope of custom parameters is always on the event-level, comparable to hit scope. This also applies to custom dimensions that automatically translate to parameters (for gtag.js "UA-XXXXXXXX" implementations), independent of the original custom dimension scope setting.

The same mapping and considerations apply for custom metrics, except they count towards numeric parameter limits instead of text parameter limits when registered for reporting.

Conceptually, custom dimensions and metrics of varying scope in a Universal Analytics property map to a Google Analytics 4 property as:
  • Hit-scoped custom dimension: parameter (max 25 total parameters logged per event during data collection; max 50 string/50 numeric registered for reporting via UI)
    Please note that automatically collected events & parameters may already cover for some use cases where previously a hit-scoped custom dimensions would have been used
  • User-scoped custom dimension: user-properties (max 25 registered for reporting via UI). Automatically collected user properties do not count towards this limit.
  • Session-scope custom dimension: no equivalent in Google Analytics 4 properties; look to custom parameters or user properties instead.

Best Practices for User Properties

User properties are similar to user-scoped custom dimensions. This means they stick to a user across different platforms (e.g. across all datastream types) and should therefore only be used if the data should apply on the user level.

User properties should not be used for session level data or device level data (e.g.screen size).

Google Analytics 4 property example

gtag('set', 'user_properties', {

favorite_composer: 'Mahler',

favorite_instrument: 'double bass',

season_ticketholder: 'true'

});

 

Add your tag using Google Tag Manager

Enable basic data collection

To enable basic data collection of events (including pageview and other automatic and enhanced measurement events) for a web data stream, you'll need to deploy the Google Analytics: GA4 Configuration tag to every page that needs to be measured. The tag initializes Google Analytics for your property, sets Google Analytics cookies, and sends automatic and enhanced measurement events (including pageviews).

To create a GA4 Configuration tag:

  1. Click Tags and then New.
  2. Click Tag Configuration.
  3. Select Google Analytics: GA4 Configuration.
  4. Enter your measurement ID.
  5. Optional: Add any parameters you'd like to configure in Fields to Set. Use recommended event parameter names for best results.
  6. Optional: Add any custom user properties that you'd like to configure in User Properties. Note: Analytics automatically logs some user properties. You can set up to 25 additional user properties per Google Analytics 4 property.
  7. Optional: Use Advanced Settings to set a Tag Firing Priority or use Tag Sequencing to help ensure that the Configuration tag fires before any other event tags that require it.
  8. Click Triggering and select appropriate triggers that would cause the tag to fire, e.g. "All Pages", so that the configuration tag fires on all pages of your website.
  9. Save the tag configuration and publish your container.

Basic data collection provides rich measurement capabilities via page_view events, automatically collected events and enhanced measurement. In addition to automatic and enhanced measurement events, you can add recommended and custom events to track actions such as clicks on specific buttons or links, user flows through sign up or account creation journeys, and navigational elements.

Event tagging

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.

Add recommended events, custom events, and custom parameters

If you currently use Universal Analytics tags to collect any events that can be automatically collected via enhanced measurement, you should use the enhanced measurement events instead of manually instrumenting the events yourself. If the enhanced measurement events do not meet your needs, follow the steps below to set up Google Analytics 4 Event tags.

The Google Analytics 4 Event tag lets you send custom events to Analytics, in addition to the events that are sent automatically or through enhanced measurement. For example, if you want to collect more detailed scroll depth data than what is provided via enhanced measurement, you can trigger a Google Analytics 4 Event tag to fire based on Tag Manager’s scroll depth trigger.

To create a Google Analytics 4 Event tag:

  1. Click Tags and then New.
  2. Click Tag Configuration.
  3. Select Google Analytics: GA4 Event.
  4. For Configuration Tag, select the Configuration Tag you created earlier.
  5. For Event Name, specify the name of the event. Use the recommended event names for best results.
  6. Optional: Enter Event Parameters. Use recommended event parameter names for best results.
    1. Click Add Row.
    2. Enter a Parameter Name.
    3. Enter a Value.
    4. Repeat until all desired parameters have been added.
  7. Optional: Add any custom user properties that you'd like to configure in User Properties. Note: Analytics automatically logs some user properties. You can set up to 25 additional user properties per Google Analytics 4 property.
  8. Optional: Use Advanced Settings to set a Tag Firing Priority, or use Tag Sequencing to help ensure that the Configuration tag fires before any other event tags that require it.
  9. Click Triggering and select appropriate events that would cause the tag to fire.
  10. Save the tag configuration and publish your container.

Example Event tag configuration:

  • Event Name: scroll
  • Parameter Name: percent_scrolled
  • Parameter Value: {{Scroll Depth Threshold}} (populated by built-in variable)
Use Advanced Settings and then Tag Sequencing to specify that an Event tag should fire after a Configuration tag.

Follow the recommended event schema whenever possible when defining the event and parameter names. Example schema shown below; full schema here.

Event Trigger... Parameters
login when a user logs in. method
purchase when a user completes a purchase transactions_id, value, currency, tax, shipping, items, coupon
refund when a user receives a refund transactions_id, value, currency, tax, shipping, items
search when a user searches your content search_term
select_content when a user has selected content content_type, item_id
share when a user has shared content content_type, item_id
sign_up

when a user has signed up

Allows you to see which methods of sign-up (e.g., Google account, email address, etc.) are most popular

method

Additional implementation guidance

Tag types

Universal Analytics has only one tag type, whereas Google Analytics 4 has two tag types: the GA4 Configuration tag and GA4 Event tag.

  • The GA4 Event tag references the Configuration tag and therefore depends on the Configuration tag being set up.
  • At runtime, the Configuration tag must fire before the Event tag.

To ensure that the Configuration tag is fired before the Event tag, assign a Configuration tag trigger that is guaranteed to be earlier than the Event tag’s trigger.

Overlap with automatically collected parameters

Events in Google Analytics 4 properties automatically collect a number of event parameters by default for every event. These include:

  • language
  • page_location
  • page_referrer
  • page_title
  • screen_resolution

Additionally, automatically collected events also include a number of their own automatically collected parameters. It's possible that you collect some of these parameters as custom dimensions in your Universal Analytics property. For your Google Analytics 4 property, however, you should not manually specify these as parameters since they are automatically collected for you.

Custom dimensions/metrics

Universal Analytics custom dimensions and metrics map to Google Analytics 4 event parameters or user properties, depending on scope. You can carry over the custom dimensions/metrics from Universal Analytics tags to Google Analytics 4 tags as follows:

  • hit-scoped → assign to GA4 Event tag as events or event parameters
  • session-scoped → In Google Analytics 4 properties, there is no need for session-scoped as dimension and metric values largely map to user properties and events or parameters.
  • user-scoped → assign to GA4 Configuration tag as user properties, to assign to GA4 Event tag using the “user_properties” parameter in “Fields to Set”.
  • product-scoped → map to ecommerce parameters

Persist settings across events

Universal Analytics makes use of a “Google Analytics Settings” variable to persist tag settings (e.g. tracking ID, cookie domain, or disable advertising features) that need to be consistent across Universal Analytics tags. You can similarly persist settings across GA4 Event tags using the GA4 Configuration tag. GA4 Event tags inherit the parameters and user properties of the linked GA4 Configuration tag.

Interaction between on-page gtag.js code and Tag Manager GA4 tags

If you have both a gtag.js implementation and a Tag Manager GA4 implementation on the same page, the on-page gtag.js code may have an impact on the Tag Manager GA4 tags.

  • On-page events fired from gtag.js command gtag('event', eventName, eventParams) without a “send_to” parameter will be collected by the Google Analytics 4 property deployed via Tag Manager.
  • Some settings parameters, such as “cookie_prefix”, or “allow_ad_personalization_signals”, assigned via the on-page gtag('set', paramName, paramValue) command will propagate the parameters to GA4 tags fired from Tag Manager.
Add gtag.js directly to web pages that are already tagged with analytics.js 

You'll need to add the Analytics tag to your website to begin seeing data in the Google Analytics 4 property you created. Keep your existing analytics.js snippet on the page. The existing snippet will continue to collect data for your Universal Analytics property.

  1. Click Admin.
  2. In the Account column, check that you have the desired account selected (directly below the "+Create Account" button at the top). 
  3. In the Property column, check that you have the desired property selected, then click Data Streams, then Web. Click the data stream.
  4. Under Tagging Instructions, click Add new on-page tag and look for "Global Site Tag (gtag.js)". Your Analytics page tag is the entire section of code that appears, beginning with:
    <!-- Global Site Tag (gtag.js) - Google Analytics -->
    and ending with
    </script>
  5. Copy and paste your entire Analytics page tag immediately after the <head> on each page of your website.

You can then use the Realtime report to verify that you're receiving data in your Google Analytics 4 property.

Implementation guide (if you have have advanced instrumentation needs)

If you want to understand how analytics.js for a Universal Analytics (UA) property maps to the gtag.js for a Google Analytics 4 property or want advanced implementation guidance, read the sections below.

About the gtag.js snippet

If you use analytics.js for your current Universal Analytics property, you'll need to add the gtag.js snippet for your new Google Analytics 4 property. The gtag.js snippet has 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 7: The gtag "config" directive enables data collection to the property associated with <Some Property ID A>. For example, adding this directive with a Measurement ID for a Google Analytics 4 property will send page_view events to that property.

The property ID may represent different Google products, including UA property ("UA-XXXXXXXX"), Google Analytics 4 property ("G-XXXXXXXX"), 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 "routes" 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>.

Basic data collection for a Google Analytics 4 property is enabled via the gtag "config" directive and enables the collection of page_view events as an automatically collected event when it loads on a page.

The pageview hit or page_view event can be modified or blocked using specific parameters.

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."

Enable basic data collection

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

In this guide, "basic data collection" means enabling these three sets of event measurement. This is in contrast to "advanced implementation," which refers to manually implementing specific events.

To enable basic data collection for your Google Analytics 4 property, add the gtag.js snippet (the global site tag) to the <head> section of each page. (For instructions on how to find your global site tag, expand the "Find your Measurement ID (Google Analytics 4)" section in this article.) Your existing Universal Analytics property remains unaffected and will continue to collect data.

gtag.js snippet compared to the analytics.js snippet

The gtag.js snippet for a Google Analytics 4 property serves a similar purpose to the analytics.js snippet for a Universal Analytics property.

The biggest difference between these two snippets is that the analytics.js code includes a separate "send pageview" call, while the gtag.js code doesn't. In gtag.js, the pageview is an automatically collected event sent along with the "config" directive.

 

Universal Analytics property (analytics.js)

<script>

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

ga('create', 'MEASUREMENT_ID', 'auto');

ga('send', 'pageview');

</script>

Google Analytics 4 property (gtag.js)

<script async src="https://www.googletagmanager.com/gtag/js?id=MEASUREMENT_ID"></script>

<script>

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

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

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

gtag('config', 'MEASUREMENT_ID');

</script>

Configuration settings for gtag.js

You can configure the basic gtag.js snippet to control data collection settings like IP anonymization, cookie customizations, and Google Signals similar to analytics.js. You do this via "config" or "set" directives in gtag.js (versus via the "set," "create" and "require" directives in analytics.js.)

Google Analytics 4 ("G-XXXXXXXX") properties support implementing similar config settings via gtag.js. There are differences between these settings for Universal Analytics and Google Analytics 4 properties. Note the following considerations:

  • 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 in gtag.js should be used in order to apply to all Measurement IDs and/or property IDs.
  • Pay specific attention to Advertising and Ad Personalization Features in analytics.js, which are most typically implemented with a "set" line.

If you use "set," "create" and "require" directives in your current analytics.js implementation, review which ones are automatically set in a Google Analytics 4 property and which ones need to be specified in the Google Analytics 4 property code (parameter mapping).

Some example configurations with their code samples in analytics.js (for the UA property) and gtag.js (for the Google Analytics 4 property) are outlined below:

Enable basic data collection; configure User-ID

analytics.js

ga('create', 'GA_MEASUREMENT_ID', 'auto', {

userId: USER_ID

});

ga('send', 'pageview');

gtag.js

gtag('config', 'GA_MEASUREMENT_ID', {

'user_id': 'USER_ID'

});

Configure cookie settings

analytics.js

ga('create', 'GA_MEASUREMENT_ID', {

'cookieName': 'gaCookie',

'cookieDomain': 'blog.example.co.uk',

'cookieExpires': 60 * 60 * 24 * 28 // Time in seconds.

});

gtag.js

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 where a page_view event is sent, followed by a user logging in to the site. For the login interaction, you'd use a "config" directive to set the user ID, but you wouldn'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

});

Tag Names

Tag names (known as "trackers") are used if you want to send data to different Universal Analytics properties in analytics.js. In analytics.js, the trackers define which property you want to send the data to. Hits after the initial "create" hit no longer need to specify the Universal Analytics property ID, only the tracker name.

In gtag.js, trackers are not available for either Google Analytics 4 or Universal Analytics properties. If you want to send all hits to multiple properties (different data streams in a Google Analytics 4 property), you specify all the Measurement or property IDs in the "config" line.

Advanced implementation

Basic data collection provides rich measurement capabilities via page_view events, automatically collected events and enhanced measurement. However, you may have additional instrumentation for your Universal Analytics property that needs to be translated over to the new Google Analytics 4 property.

Event Tagging

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.

A valid and direct translation of a Universal Analytics property event (implemented in analytics.js) to a Google Analytics 4 property event might look as follows:

UA property event (via analytics.js)

ga('send', 'event', 'Videos', 'play', 'Fall Campaign');

OR

ga('send', {

hitType: 'event',

eventCategory: 'Videos',

eventAction: 'play',

eventLabel: 'Fall Campaign'

});

Google Analytics 4 property event (via gtag.js)

gtag('event', 'play', {

'eventCategory': 'Videos',

'eventLabel': "'Fall Campaign'

});

Naming conventions for manually implemented events

If you use an "Event Name" value that is not on the automatically collected event names list 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 be compatible with additional reporting and future functionalities in Google Analytics 4 properties, which will rely on these naming conventions.

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. However, in order for you to see them in the reporting interface, you'll need to register them. Registration makes these parameters available as event-scoped custom dimensions or event-scoped custom metrics in reports.

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. See below under "Limits for event collection" for more details.
  • There is a total registration limit of 50 custom text and 50 numeric parameters per property.

Recommendations

  1. Start collecting the data. Do not register parameters yet. Review the event data in BigQuery.
  2. Review which of the existing events are already covered by automatically collected events and enhanced measurement.
  3. Implement recommended events wherever possible.
  4. Register parameters as necessary.

Custom dimensions and metrics

Custom dimensions and metrics are used to extend information that is measured on the website, and for importing offline data from e.g. CRM systems. In a Universal Analytics property ("UA-XXXXXXXX" ), custom dimensions and metrics need to be created in the UI, are assigned an ID, and can then be implemented or imported. They can be created with four different scopes: hit, session, user, product.

In a Google Analytics 4 property ("G-XXXXXXXX"), the custom dimensions and metrics use case is implemented in a different way. Custom dimensions and metrics measurements in UA property implemented via analytics.js need to be re-implemented as parameters in a Google Analytics 4 property.

A custom dimension for a Universal Analytics property may be implemented via analytics.js as follows:

ga('send', 'event', 'category_value', 'action_name', {'dimension5': 'custom data'

});

OR

ga('set', 'dimension5', 'custom data');

 

These custom dimensions can be translated to a Google Analytics 4 property via gtag.js as follows:

gtag('event', 'action_name', {'eventCategory': 'category_value',

'dimension5': 'custom data'

});

OR

gtag('set', {'dimension5': 'custom data'});

There are two caveats:

  1. Parameters need to be registered in the user interface to appear in reports. This is a comparable process to registering custom dimensions in Universal Analytics (limits apply). You don't need to register them if you are only looking at exported data or only use the parameter for audience activation.
  2. The scope of custom parameters is always on the event-level, comparable to hit scope. This also applies to custom dimensions that automatically translate to parameters (for gtag.js "UA-XXXXXXXX" implementations), independent of the original custom dimension scope setting.

The same mapping and considerations apply for custom metrics, except they count towards numeric parameter limits instead of text parameter limits when registered for reporting.

Conceptually, custom dimensions and metrics of varying scope in a Universal Analytics property map to a Google Analytics 4 property as:

  • Hit-scoped custom dimension: parameter (max 25 total parameters logged per event during data collection; max 50 string/50 numeric registered for reporting via UI)
    Please note that automatically collected events & parameters may already cover some use cases where previously a hit-scoped custom dimensions would have been used
  • User-scoped custom dimension: user-properties (max 25 registered for reporting via UI). Automatically collected user properties do not count towards this limit.
  • Session-scope custom dimension: no equivalent in Google Analytics 4 property; look to custom parameters or user properties instead.

Best practices for user properties

User properties are similar to user-scoped custom dimensions. This means they stick to a user across different platforms (e.g. across all data stream types) and should therefore only be used if the data should apply on the user level.

User properties should not be used for session level data or device level data (e.g.screen size).

Google Analytics 4 property example

gtag('set', 'user_properties', {

favorite_composer: 'Mahler',

favorite_instrument: 'double bass',

season_ticketholder: 'true'

});

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue