Translating Website Tags from Universal Analytics to Google Analytics 4

Change is hard.

It might seem simple to migrate your Google Analytics code from a Universal Analytics property to Google Analytics 4 (or GA4), but the first time I did this for a client was a complete mess. The tips and best practices that I've compiled below will help you learn from my mistakes as you map your existing Universal Analytics tags into the new GA4 tags using either gtag or Google Tag Manager.

If you are looking for conceptual differences between the two versions of Google Analytics, check out my post on the Differences Between Traditional Google Analytics and Google Analytics 4.


The Data Schema

As I've discussed at length in other posts, Google Analytics 4 uses the event-driven data model. This means that data is collected in three simple components:

  • Events - Identify that something important happened
  • Event Parameters - Information that describes the event
  • User Properties - Information that describe the user who triggered the event

Although the simplicity of this new event-driven data schema makes it vastly more flexible, it also creates confusion around the best way to translate familiar variables to the new format. Let's start with the most common questions and work our way down into the edge cases.

The Page View Tag

The traditional approach to firing a page view with Analytics.js and Google Tag Manager was to set all of your variables and then fire a page view tag. However, if you've used the gtag, you might have noticed that the process changed slightly so that a page view automatically fires with the "config" event, like so:

1// Fire a page view using Analytics.js
2ga('send', 'pageview');
4// Fire a page view using the gtag
5gtag('config', 'UA-XXXXX-X');

This concept applies to Google Analytics 4 as well. As a general rule of thumb, you can think of the new "Configuration Tag" as a combination of the "Google Analytics Settings" variable and a "Page View" tag.

If all or a portion of your website is built using a Single Page App, you may need to make an additional change. You can take a look at my post called Using Google Analytics 4 with Single Page Apps to learn more.

Custom Event Tags

You might be tempted to skip this section… obviously a custom event tag maps to an "Event" tag. But you actually need to be very careful about how you migrate your custom events when using GA4.

Google provides a list of Recommended events that automatically enable reporting features that are unavailable with custom events. This is because Google Analytics 4 does not know what your custom events are intended to represent.

For example, if you create an event called "pageview" you will get a very simple report that displays how frequently this event occurs. But if you use the recommended "page_view" event name you will see a new chart that displays how much engagement you are getting by page title or page path.

User engagement by page

Beware of Event Parameter Limits

I know it's tempting, but do not create event properties called "category", "action", and "label". This is the lazy type of thing a developer would do, and you're better than that. Instead, be thoughtful about how you would like your reports to appear and design a strategy around that.

Here are two things to consider:

  1. You get 100 custom definitions (metrics or dimensions) in a Google Analytics 4 property (source). Your custom definitions are created automatically by your event parameters, so you should plan these in advance.

    For more detail on custom definitions in GA4, check out THIS article.

  2. You only get 500 distinct events (source), so be careful not to create too many unique names.

    For more tips on how to properly set up events and parameters, check out THIS article.

No More Non-Interaction Flags

The non-interaction flag is not necessary any more, because "Bounce rate" is being replaced by "Engaged Sessions". This is a much smarter metric for representing user engagement, and there's nothing you need to configure for it to work. You can read more about this in my post: Where did bounce rate go in Google Analytics 4?

Persistent Variables

Persistent variables are those that should be applied to all hits, such as: the tracking ID, certain custom dimensions like the user's current login status, or other settings like disabling advertising features. If you've used Google Tag Manager on the web in the past, these were set in the "Google Analytics Settings" variable.

In Google Analytics 4, these variables are now applied within the "Configuration Tag"

Configuration Tag

Fields to Set

If you previously used the "Fields to Set" portion of the Google Analytics Settings variable, you might be able to migrate these settings directly into the Google Analytics 4 Configuration tag, but many of the field names have changed.

No errors are thrown when you set a field with an unrecognized field name (the field will be set as an event parameter), so be careful and use the table below to confirm your variable name is correct:

Universal Analytics Google Analytics 4
language "language"
location "page_location"
title "page_title"
referrer "page_referrer"
screenResolution "screen_resolution"
userId "user_id"
allowAdFeatures "allow_google_signals"
(set to "false")
cookiePath "cookie_path"
cookieDomain "cookie_domain"
cookieExpires "cookie_expires"
cookieName "cookie_prefix"
(use this to separate cookies for multiple properties or prevent conflicts with preexisting cookies)
cookieUpdate "cookie_update"
cookieFlags "cookie_flags"
(use this to set the sameSite flag)
allowLinker "linker"
contentGroup "content_group".
anonymizeIp n/a
(IPs are anonymized by default)
customTask Not supported.
siteSpeedSampleRate Not supported.
campaignSource Not supported.
campaignMedium Not supported.
campaignName Not supported.
hitCallback Not supported.

Other Persistent Variables

The Google Analytics Settings variable also allowed you to set several other types of persistent variables, such as Custom Dimensions, Custom Metrics, Ecommerce, etc. Each of these has been detailed below, so please read through the following content to determine if the additional variables should be set with the "Configuration Tag" or moved to an "Event Tag".

Custom Dimensions

In Google Analytics 4, the scope of your custom dimensions will be set to the hit level or the user level. Product-scoped custom dimensions will now be set as item parameters.

For more detail, check out my article on How to Set Custom Dimensions and Metrics in Google Analytics 4.

Custom Metrics

Your custom metrics will be set as Event Parameters, just be sure that your data type is not set to a string so that these will be classified as "Numeric" event parameters as opposed to "Textual" event parameters.

Content Groups

Content groups in Google Analytics can utilize the predefined event parameter called "content_group" in gtag.js or "Content Group" in GTM.

Social Interactions

If you were previously using the "social" event type when a user shared content over social media, you will replace this with the "share" event. This event comes with two parameters:

  1. content_type: I usually set this to the "Social Network" (ie. Facebook)
  2. item_id: Set to the "Action Target" (what was shared)


It is important that you carefully follow Google's guidelines for Recommended Ecommerce events when migrating your Ecommerce tags. The Ecommerce reports are currently very limited, but they will be built out over time and it will be painful to change this at a later date.

You can find the GA4 Ecommerce documentation using the links below: