App + Web properties tag and instrumentation guide

App + Web properties enable unified measurement of user interactions and events between web and app. If your mobile app contains embedded web views, an equivalent web app, or web pages that mirror or otherwise extend the mobile experience, you should use App + Web properties for your Google Analytics measurement strategy. App + Web properties can be implemented without any additional tag modifications if you already use gtag.js or Google Tag Manager.

How do events and parameters work with App + Web properties?

An event is any distinct action occurring at a distinct time associated with a user in your app or on your website, e.g. page_view, add_to_cart, form_submit.

You can send parameters with each event. Parameters are additional pieces of metadata that add further context to the event. For example, parameters can be used to provide context into what, where, how, and why the event was fired.

Some parameters, such as page_title, are sent automatically. In addition to the automatically sent parameters, you can send up to 25 custom parameters with each event. For a game-style event such as level_up, for example, you may want to add parameters such as level_number, character_name, etc. Or, for a content-style event such as content_view, you may want to add parameters such as article_id, article_title, author_name, author_id, and so on.

The reports in App + Web Properties provide information about the events and parameters that were sent from your app and/or website.

Initial tag setup

To get started with App + Web properties, configure your mobile app to use Firebase and Google Analytics if you have not done so already.

Next, enable a web stream for your property in Google Analytics.

To ensure your tag has been configured properly, confirm that data appears in your Google Analytics Real-Time Reports.

Events

Events provide insight on what is happening in your app, such as user actions, system events, or errors. Google Analytics logs many events automatically. You don't need to add any code to gather automatically collected event data for your reports. If your app needs to collect additional event data, you can log up to 500 different Analytics event types. There is no limit on the total volume of events your app logs.

Automatically collected events

The global site tag collects several events and user properties automatically, such as first_visit, session_start, user_engagement, and page_view.

Certain events are recommended for all apps; others are recommended for specific business types or verticals. You should send suggested events along with their prescribed parameters, to ensure maximum available detail in your App + Web property reports and to benefit from future features and integrations as they become available.

Use suggested events to capture data to generate detailed reports on event/parameter combinations, to create audiences, and to integrate with other Google products (such as Google Ads and the Google Marketing Platform).

Custom events

Custom events are events that you invent, i.e. events that are not already taken as automatic or suggested events. Before you create a new event, make sure that an equivalent suggested or automatic event does not already exist.

Custom events are collected in the same way as automatic and suggested events. However, since their names are arbitrary and not recognized by App + Web property reports, custom events must instead be analyzed via BigQuery.

To log recommended or custom events from web pages, use an event command. For example, you can use the event command to send a login event with a method value of "Google":

gtag('event', 'login', {
  'method': 'Google'
});

For more information:

Data collection and reports

You can instrument Google Analytics App + Web properties to collect information about how your content is used in many different ways. Here are a few common use cases that demonstrate how you can customize how data is sent to Google Analytics.

Page views and screen views

When an App + Web property is installed on a web page, page_view events are collected by default. The mobile equivalent of a page_view event is the screen_view event, and apps that use Firebase will automatically log relevant information about app screens as they are viewed.

In many cases, you may want to configure a web page to capture a screen_view event. This might include web pages that have identical presentation and functionality to a mobile screen view, mobile apps that have embedded WebView screens, mobile web apps, etc.

For mobile Firebase apps, Analytics will automatically log the class name of the UIViewController or Activity that is currently in focus.

For web, Analytics will log the text contents of a web page's <title> tag. Or the value can be sent explicitly with a screen_name property.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name' : 'Home'
});

Reports will appear in Google Analytics' Experimental Reporting pages. Learn more about experimental reports.

Conversions

Conversions shows how many conversion events were driven by each aspect of your marketing, along with the value of those events. You can mark any event as a conversion in Google Analytics, and some events (i.e. first_open, in_app_purchase, ecommerce_purchase) are marked as conversions by default. Learn more.

Shopping cart additions

To send item information as they are added to a shopping cart, use the add_to_cart event type. The add_to_cart event takes three parameters:

  • value: Usually set to the total value of items in the add_to_cart event.
  • currency: The regional currency assigned to the value, e.g. "USD" or "JPY".
  • items: An array of objects that represent the parameters of each item.
gtag('event', 'add_to_cart', {
  "value": 5,
  "currency": "USD",
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "category": "Apparel/T-Shirts",
      "Quantity": 2,
      "price": 19.99
    },
    {
      "id": "P67890",
      "name": "Treble Clef Tank Top",
      "category": "Apparel/T-Shirts",
      "quantity": 1,
      "price": 13.50
    }
  ]
});

In Google Analytics, you can mark add_to_cart events as conversions. Learn more about Conversion Reports.

Completed purchases

Use a purchase event to capture data when a purchase is completed.

gtag('event', 'purchase', {
  "transaction_id": "0167dc80-3fa1-4f87-8c26-518c3544f280",
  "affiliation": "Google online store",
  "value": 5.00,
  "currency": "USD",
  "tax": 0.45,
  "shipping": 0,
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "quantity": 2,
      "price": 19.99
    },
    {
      "id": "P67890",
      "name": "Treble Clef Tank Top",
      "category": "Apparel/T-Shirts",
      "quantity": 1,
      "price": 13.50
    }
  ]
});

In Google Analytics, purchase events are considered conversions automatically. Learn more about Conversion Reports.

User Properties

User properties are attributes that can be used to describe segments of your user base, such as language preference or geographic location. Analytics automatically logs some user properties. If you want to collect additional data, you can set up to 25 additional user properties per project. Learn more about User Properties reports.

Audiences

Audiences let you segment users in ways that are relevant to your business. You can combine events, parameters, and user properties along with the Source, Medium, and Campaign dimensions to create practically any subset of users. Learn more about Audiences.