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 tag 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.
Web data streams for Google Analytics 4 properties use a tag ID with the format "G-XXXXXXXX."
In some code examples and documentation, you may see both referred to as "TAG_ID."
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)
To enable basic data collection for your Google Analytics 4 property, add the gtag.js snippet (the Google tag) to the <head> section of each page.
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', 'TAG_ID', 'auto');
ga('send', 'pageview');
</script>
Google Analytics 4 property (gtag.js)
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');
</script>
Configuration settings for gtag.js
You can configure the basic gtag.js snippet to control data collection settings like IP masking, 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 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 ("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 tag 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', 'TAG_ID', 'auto', {
userId: USER_ID
});
ga('send', 'pageview');
gtag.js
gtag('config', 'TAG_ID', {
'user_id': 'USER_ID'
});
Configure cookie settings
analytics.js
ga('create', 'TAG_ID', {
'cookieName': 'gaCookie',
'cookieDomain': 'blog.example.co.uk',
'cookieExpires': 60 * 60 * 24 * 28 // Time in seconds.
});
gtag.js
gtag('config', 'TAG_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', 'TAG_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 tag IDs or property IDs in the "config" line.
Events
Refer to the Event migration guide.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:
- 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.
- 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 custom dimensions/50 custom metrics)
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 dimensions 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 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'
});