Upgrade to an App + Web property

Set up an App + Web property alongside an existing Universal Analytics ("Web") property.

This article guides you through the process of setting up an App + Web property, a new type of Google Analytics property. 

Before you begin

This article assumes that you have an existing Universal Analytics ("Web") property. Once you have finished upgrading:

  • You will have a new, functioning App + Web property

  • Your existing Universal Analytics ("Web") property will remain unchanged and will continue to collect data

Your new App + Web property will give you the opportunity to learn about App + Web reports firsthand.

Not all Web property functionality is supported in App + Web properties. However, you can continue to use your existing Universal Analytics property.

Upgrade steps

To upgrade: 

Create an App + Web property and data stream

Before creating an App + Web property, read this guidance for structuring your Analytics account around App + Web properties.

When you are ready to create your App + Web property:

  1. Sign in to Analytics.
  2. Click Admin.
  3. In the Account column, select the account in which you want to create the property. (If you only have one Google Analytics account, it will already be selected. However, if you have more than one Google Analytics account, make sure that the account you want is selected.)
  4. In the Property column, click Create Property.
  5. Select "Apps and web BETA" and click Continue.
  6. Enter a name for the property, for example, "Example, Inc (App + Web property)".
  7. Select the industry category. Google uses this information when you choose to share benchmarking data.
  8. Select the reporting time zone. Analytics uses this as the day boundary for your reports regardless of where the data originates.
  9. Select the currency you want to use for reporting. Metrics with monetary values are calculated and displayed in the currency you choose.
  10. Click Create.
  11. You now have the option to set up a data stream. Select the "Web" platform. You can add data streams for other platforms later.
  12. Enter your website URL, e.g. "example.com", and a Stream name, e.g. "Example, Inc (web stream)".
  13. You have the option to enable or disable enhanced measurement. Enhanced measurement automatically collects page views, scroll tracking, outbound link clicks, site search, and other events. Once the data stream has been created, you can always go back and individually disable the enhanced measurement events you don’t want to collect. So, we recommend that you enable enhanced measurement now.
  14. Click Create stream.

Enable data collection

Now that you have set up your App + Web property and a (web) data stream, you'll need to implement tagging on your site.  This tagging allows your App + Web reports to start getting populated with data. You won't replace the tagging that already exists for your Universal Analytics property, instead you'll add to it. So, data will flow to both your Universal Analytics property and your new App + Web property. 

The instructions are different depending upon how tagging is implemented for your Universal Analytics property. 

If you use Google Tag Manager for your existing Universal Analytics property

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: App + Web Configuration tag to every page that needs to be measured. The tag initializes Google Analytics for your App + Web property, sets Google Analytics cookies, and sends automatic and enhanced measurement events (including pageviews). 

To create an App + Web Configuration tag:

  1. Click Tags and then New.
  2. Click Tag Configuration.
  3. Select Google Analytics: App + Web 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 App + Web 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 events 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. However, you may have additional instrumentation for your Universal Analytics property that needs to be translated over to the new App + Web property.  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 separate hit types, 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 an App + Web property, every "hit" is an "event," meaning there is no longer a distinction between hit types.  

Types of events in an App + Web Property

App + Web 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 an App + Web 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
    • 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 App + Web 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 App + Web 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 an App + Web 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 App + Web Event tags. 

The App + Web 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 an App + Web Event tag to fire based on Tag Manager’s scroll depth trigger.

To create an App + Web Event tag:

  1. Click Tags and then New.
  2. Click Tag Configuration.
  3. Select Google Analytics: App + Web 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 App + Web 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 App + Web has two tag types: the App + Web Configuration tag and App + Web Event tag. 

  • The App + Web 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 App + Web 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 App + Web 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 App + Web event parameters or user properties, depending on scope. You can carry over the custom dimensions/metrics from Universal Analytics tags to App + Web tags as follows:

  • hit-scoped → assign to App + Web Event tag as events or event parameters
  • user-scoped → assign to App + Web Configuration tag as user properties, to assign to App + Web Event tag using the “user_properties” parameter in “Fields to Set”.
  • session-scoped → In App + Web, there is no need for session-scoped as dimension and metric values largely map to user properties and events or parameters. 
  • 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 App + Web Event tags using the App + Web Configuration tag. App + Web Event tags inherit the parameters and user properties of the linked App + Web Configuration tag.

Interaction between on-page gtag.js code and Tag Manager App + Web tags

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

  • On-page events fired from gtag.js command gtag('event', eventName, eventParams) without a “send_to” parameter will be collected by the App + Web 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 App + Web tags fired from Tag Manager. 
If you use gtag.js for your existing Universal Analytics property

 

If you just want to add the basic page tag to your site and start seeing your App + Web reports populated with data, read these instructions. However, if you want to understand how gtag.js for a Universal Analytics (UA) property maps to an App + Web 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 an App + Web 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 App + Web 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 App + Web 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 an App + Web 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 an App + Web 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"), an App + Web 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>.

Regardless of whether you are implementing an App + Web 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 an App + Web property, the "config" with an App + Web 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.

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

  • Option 1: Adding a new "config" directive with the relevant App + Web 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 App + Web property's Measurement ID. In the example below, line 8 has been added to an existing gtag.js implementation. It references the App + Web property's Measurement ID. This will send page_view events to that App + Web property. It also enables automatically collected events and enhanced measurement events (if you have enabled enhanced measurement) in that App + Web 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 App + Web property. However, you'd only encounter this situation if an App + Web property has already been implemented.)

  • AND you have admin access to the Universal Analytics property referenced by the ID in the snippet.

If the above two points are both true,  follow these instructions.

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 App + Web ("G-XXXXXXXX") properties support implementing these config settings via gtag.js. However, there are a few differences between these settings for Universal Analytics and App + Web properties. Note the following considerations.

  • IP Anonymization is standardized to "true" and not configurable in an App + Web property. As such, the IP address is automatically masked with the standard event to App + Web 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 App + Web property. If you want the configuration to apply to the connected App + Web property,
    • Create a separate "config" directive and apply it to the relevant App + Web 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 App + Web property. 

Event tagging

In a Universal Analytics property implemented via gtag.js ("UA-XXXXXXXX"), events are implemented as separate hit types, 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 an App + Web property, every "hit" is an "event," meaning there is no longer a distinction between hit types.  

Types of events in an App + Web Property

App + Web 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. Automatically collected events DO NOT REQUIRE adding/modifying code on web or in app.
  2. Enhanced measurement provides events that you can toggle on and off using the Admin interface within an App + Web 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 an App + Web property, the solution is to add a "send_to" parameter in the event specifying the relevant UA property ID. That way, the event only flows to the Universal Analytics property and not to the App + Web 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 App + Web 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 App + Web 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 an App + Web 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 an App + Web property ("G-XXXXXXXX") whenever an App + Web Measurement ID 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 App + Web property. 
  • Event Category, Label, and Value become parameters in the App + Web property. You need to register these parameters in order for them to appear in your App + Web reports. There are also limits, 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 an App + Web 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 App + Web 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 App + Web 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. 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 an App + Web 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

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 an App + Web property according to the following logic:

  • "Download" becomes the Event Name 
  • "event_category" becomes a custom parameter. You will need to register it as a parameter for it to be visible in reporting.
  • "event_label" becomes a custom parameter. You will need to register it as a parameter for it to be visible in reporting. 

A more generalized event structure would then look like this:

  • event_category: [resourceType]
  • action: [interactonType]
  • 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 App + Web 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. 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. Add a ‘send_to’ command to send these events only to your Universal Analytics property implementation and not to your App + Web property. 
  3. Implement recommended events wherever possible.
  4. Register parameters as necessary.

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

 

App + Web property example

gtag('set', 'user_properties', {

  favorite_composer: 'Mahler',

  favorite_instrument: 'double bass',

  season_ticketholder: 'true'

});

 

If you use analytics.js for your existing Universal Analytics property

 

If you just want to add the basic page tag to your site and start seeing your App + Web reports populated with data, read these instructions. However, if you want to understand how analytics.js for a Universal Analytics (UA) property maps to the gtag.js for an App + Web property and want in-depth 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 App + Web 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 an App + Web property will send page_view events to that property. 

The property ID may represent different Google products, including UA property ("UA-XXXXXXXX"), App+Web 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 an App+Web 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.

App + Web 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 an App + Web 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 App + Web 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 (App + Web properties)" 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 an App + Web 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>

 

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

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

  • IP Anonymization is standardized to "true" and not configurable in an App + Web property. As such, the IP address is automatically masked with the standard event to App+Web 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 an App+Web property and which ones need to be specified in the App + Web property code (parameter mapping).

Some example configurations with their code samples in analytics.js (for the UA property) and gtag.js (for the App+Web 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 App + Web or Universal Analytics properties. If you want to send all hits to multiple properties (different data streams in an App + Web 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 App + Web property. 

Event Tagging

In Universal Analytics properties implemented via gtag.js ("UA-XXXXXXXX"), events are implemented as separate hit types, 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 an App + Web property, every "hit" is an "event," meaning there is no longer a distinction between hit types.  

Types of events in App + Web Property

App + Web 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. Automatically collected events DO NOT REQUIRE adding/modifying code on web or in app. 
  2. Enhanced measurement provides events that you can toggle on and off using the Admin interface within an App + Web 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 an App + Web property, the solution is to add a "send_to" parameter in the event specifying the relevant UA property ID. That way, the event only flows to the Universal Analytics property and not to App + Web 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 specific 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 App + Web 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 App + Web 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 an App + Web 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 an App+Web 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'

});

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

App+Web property example

gtag('set', 'user_properties', {

  favorite_composer: 'Mahler',

  favorite_instrument: 'double bass',

  season_ticketholder: 'true'

});

 

Enable conversion events

Where you previously created goals, you now enable events as conversions.

Was this helpful?
How can we improve it?