Old to New

Translating Website Tags from Universal Analytics to App + Web

It might seem simple to migrate your Google Analytics code from a Universal Analytics property to a new App + Web property, 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 App + Web 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 App + Web Properties.

The Firebase Data Schema

As I’ve discussed at length in other posts, the new App + Web properties that are used with Google Analytics for Firebase replace the traditional tag types (“Page View”, “Event”, etc.) with the following three components:

  • Events
  • Event Parameters
  • User Properties

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:

// Fire a page view using Analytics.js
ga('send', 'pageview');

// Fire a page view using the gtag
gtag('config', 'UA-XXXXX-X');

This concept has been adopted to the App + Web properties 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.

Unfortunately there are some exceptions to this rule. Before you create the Configuration Tag and move on to the next step you should take a look at my post called Should You Manually Set the Page_View Event in an App + Web Property?

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 an App + Web property.

Utilize Recommended Events Where Possible

Google provides a list of Recommended events that automatically enable reporting features that are unavailable with custom events. This is because App + Web properties do 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.

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 500 distinct events, but only 50 textual custom parameters (source). If a parameter is duplicated on two different events, that counts as 2 parameters. So if you use “category”, “action”, and “label” to track 5 different events, you’ve used up 15 of your parameter slots already.
  2. Creating clear and intuitive event parameter names will reduce the number of questions you get from coworkers who are trying to use the event reports.

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.

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 an App + Web property, these variables are now applied within the “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 App + Web 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 App + Web
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 Not supported.
See “Content Groups” below.
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

When migrating custom dimensions, you should consider two things:

  1. The scope of the dimension: User, Session, Hit, or Product
  2. Does the dimension need to be placed in the Configuration Tag so that it will persist across events

The chart below illustrates how custom dimensions should be mapped to variables within your App + Web property.

Scope (UA) App + Web Variable
Hit Event Parameter
Session No equivalent
User User Property
Product Ecommerce Parameter

App + Web properties do not have any equivalent to a session scoped custom dimension. Instead, these will typically be migrated to event parameters. If you do a lot of reporting on session scoped custom dimensions it will be helpful to enable the BigQuery Integration and review my post on Using BigQuery and Data Studio.

Custom Metrics

Your custom metrics will be migrated 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

There is no designated variable for content groups in an App + Web property, but you can accomplish the same goal with a simple event parameter.

I recommend adding your content groups under “Fields to Set” in the Configuration tag so that they will be set with every event. Then open the “All Events” report and “Edit parameter reporting” as shown below to enable the content group in your “page_view” event report.

Edit parameter reporting for the page_view event

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 Google’s App + Web Ecommerce documentation using the links below:

Items That Do Not Translate

At this time App + Web properties are still in beta, and several important features have not been built within App + Web properties. I will update this post as these come available in the future, but for now you’ll have to live without them:

  • Cross-domain tracking
  • Custom Tasks
  • User timing

Leave a Reply

Your email address will not be published.