SHARE
Events
After migrating priority UA goals, recreate UA events by mapping to GA4 event types, and recreating each as a recommended or custom GA4 event.
Key Tasks
- Map legacy UA events against auto-collected events and recommended events
- Recreate UA events as recommended events
- Recreate UA events as custom events
- Recreate UA events based on auto-collected events with custom parameters
- Create events for apps
- Create ecommerce events
The Event Data Model
The GA4 data model is more flexible with fewer restrictions and required fields/parameters than the UA model. In UA, when you send an event, you need to send an Event Category and Event Action for each event. You might also include an event label and the event value. In GA4, the model is simply event name + any parameters needed. No category and action.
Data is more meaningful when each parameter is named by function. The model structure is more flexible as up to 25 parameters can be used to describe specific events. And finally, the taxonomy works across app and web.
Aligning app and web events
While the flexible structure of GA4 simplifies configuration, the agnostic data collection approach captures cross-platform insights from event data. When GA4 properties combine app and web measurement, ensure that event data collection is consistent across app and web.
- The same events should be named the same, regardless of data source (e.g., premium_purchase for web should not be represented as prime_purchase on app).
- The same events should have the same associated parameters (e.g., store_unit for web should not be store_number on app for same data element parameters).
- The values passed should be of the same type for both data streams (e.g., if a store_unit is numerical in web, the app should not be a different value type).
About Dual Tagging
Using gtag.js for dual tagging
Some GA users who are unable to make code-level changes to their website choose to repurpose UA tagging for their GA4 implementation. If your UA implementation uses gtag.js, this dual tagging is usually achieved through the GA4 Setup Assistant when selecting the option “Enable data collection using your existing tags” (enabling connected site tags).
When events implemented in UA are translated to GA4, the event action becomes the event name, and the event category, label, value become event parameters for the GA4 property. While this automatic event translation is a quick option, the resulting string of automated parameters limits the value of the GA4 structure and taxonomy.
Moreover, the automatically collected events (including enhanced measurements) can double count any parallel event that is also manually captured in the UA event implementation. At a minimum, these automatically collected GA4 events should be disabled. Ideally, Google recommends planning the implementation with some expectation of manual tagging.
Monetization Overview Report
Dual Tagging and Ecommerce Events Migration
An ecommerce migration is mission critical and complicated. The variations between UA and GA4 structures, including the specific recommended events and dependencies (e.g, reports), demand an intentional tagging approach that addresses user considerations. The GA Developer Migration Center provides specific options for both gtag.js and GTM when migrating ecommerce events from UA to GA4. It is possible to send the same ecommerce events to both a UA and GA4 property if intentionally configured with either gtag.js or GTM.
Dual Tagging using GTM
Map UA events to GA4 events
After capturing your priority UA configuration during implementation planning, the next step in event migration is to map legacy events to the GA4 event types, the same types used for mapping legacy UA goals.
Event types
As noted in the Goals Migration section, GA4 events fall into three main categories:
- Automatically-Collected Events: refers to both, the automatically-collected events that are always enabled, and the enhanced event measurement that is activated and configurable from the UI. These require no extra work for tracking as long as the core GA4 tracking tag is enabled through Google Tag, Google Tag Manager, or the GA for Firebase SDK.
- Recommended Events: refers to events that must be implemented with event-specific code to activate and require specific naming conventions and parameter recommendations in order to effectively work within GA.
- Custom Events: refers to those events that must be implemented with event- and parameter-specific code, but have no naming or parameter guidelines and restrictions.
Process for Mapping Events
For each UA event, look for a match first in auto-collected events, then in recommended events, and create a custom event if no match is found in either.
First, check the auto-collected events tables for a matching event.
Auto-collected Events Table
- For each UA event, look for a matching auto-collected or enhanced measurement event.
- If a match is found, do not recreate a new event. The event will automatically be captured with the built-in parameter(s) listed in the table definition.
- If no match is found, proceed to recommended events.
Second, check the recommended event tables for a matching event.
Recommended Events Table
- If no automatically-collected event was found, look for a matching recommended event.
- If found, implement your tagging to trigger the recommended event. Remember, use the nomenclature from GA’s recommended events table for both event and parameters. Because GA4 uses recommended elements for calculations and reports, creating custom versions of recommended events (i.e., different names/parameters) defeats the purpose and value.
- If no match is found, create a custom event.
Building Out GA4 Events
Steps for creating events vary according to the tagging approach. However, the examples and syntax below convey the general logic for creating recommended and custom events.
Create a Recommended Event (GTM)
Both recommended and custom events must be implemented in order to activate in GA4. The difference is that recommended events schema has been defined so that these events (when implemented) are treated differently in the reporting UI, and some appear in built-in reports (e.g., some online-sales events in the Monetization reports). Not all recommended events currently populate built-in reports, but they may when new reports become available in the future.
Event steps below assume you have added the Tag Manager snippet to your website and created a GA4 Configuration tag enabling core GA4 tracking. For each event, create an event tag using the recommended name, add parameter(s).
- In GTM, click Tags > New
- For Tag Configuration Type, Select Google Analytics: GA4 Event
- For the Configuration Tag, select GA4 Configuration Tag (this is your existing configuration tag that contains your GA4 Measurement ID)
- In Event Name, enter the name of the event (exactly as in GA's support tables for recommended events)
- Add any Parameters by clicking Add Row, enter name of parameter (exactly as in GA's support tables for recommended events)
GTM UI Recommended Event example
In this example, the recommended ecommerce event view item list is created, including the predefined parameter "item_list_name." The event is sent when a user views a list of items/offerings, and can capture the name or ID of the list in a string.
DebugView
Each time a new tag is created in GTM, use GTM's built-in Preview mode in conjunction with GA4's DebugView before publishing. After you have added the appropriate trigger to an event, the data will scroll in real time. Clicking the event in the Seconds Stream will verify any parameter and value assigned. Once verified, publish the container. See the Tagging and Tracking section for more information on validating tags.
Remember, always check the list of automatically collected (and enhanced measurement) and recommended events before creating a custom event. These events populate existing dimensions and metrics, and don't count against the limits of events and parameters per property.
Create a Custom Event (GTM)
When no equivalent auto collected or recommended event is available in GA4, use your naming conventions for custom events and parameters. For example, to capture a specific navigational click on your site: ‘navigation-click” could be the event name, ‘click-location=top’ and ‘click_text=company-about-us’ could be custom parameters.
Specifics on mapping UA events/custom dimensions to GA4 are based on each event’s original identity and parameters. Custom dimensions can be used to maintain those defined in UA; however, many of the UA values that were tracked as event dimensions in UA, such as event category and event label, should be recreated in GA4 as custom dimensions. Using GTM for custom events follows the same creation process as a recommended event.
Creating Events Using Google Tag
After gtag.js snippets have been added immediately after the to the <head> on each page of your website, you can use Google Tag syntax to create events in your property. The syntax for event creation itself is simple.
Google Tag Syntax
In this case, the 'event' command tells Google to send an event, followed by the name of the recommended or custom event, and optionally (and likely) the parameters that include additional information. However, using the Google Tag for complex ecommerce events demands a high level of proficiency with the environment. For an example, along with links to the API library, review the developers guides for GA4 Measurement.
Developers Guide view_item_list Example
Modifying an Auto-collected Event
If an auto-collected event partially matches but does not fulfill the need of an existing UA event, you must modify the event/parameter to meet your needs. However, parameters for auto-collected events cannot be modified with additional custom parameters.
Auto-collected scroll Event
For example, many users noted that the built-in scroll event would be more useful if configured differently. The current scroll event captured by enhanced measurement tracks users only when they reach the bottom of a page (90% vertical depth). Because built-in events and parameters are not customizable, a custom event solution cannot overlap the existing built-in event.
As a result, two options exist:
- Disable an auto-collected event, then recreate as a custom event and parameter that captures all necessary data; or
- Leave the auto-collected event in place, but augment with a custom event and parameters that do not overlap the auto-collected event.
Replacing Auto-collected Event with Custom Event & Parameter (GTM).
As in the recommended event example above, create a new event connected to your existing configuration tag. However, to create a more flexible "scroll" event, create a new event parameter.
- In GTM, click Tags > New
- For Tag Configuration Type, Select Google Analytics: GA4 Event
- For the Configuration Tag, select GA4 Configuration Tag (this is your existing configuration tag that contains your GA4 Measurement ID)
- In Event Name, enter "Scroll" as the name of the event
- Click Add Row, enter "scroll_depth" as the name of the parameter
- For the Value, enter , a built-in variable that will pull scroll percentages.
- Create a Trigger by clicking the Trigger area at bottom of the workspace, and select Scroll Depth Trigger. Modify vertical (or horizontal), and set a percentage instead of pixel depth.
- Save the Trigger and Tag, test using GTM's Preview mode and GA4's DebugView.
GTM UI with Custom Parameter for Auto-Collected Event
Creating Events for Apps
After installing GA for Firebase SDK, you can begin to log events using the logEvent( ) method. This method is similar to the event command in gtag.js. The GA SDK defines common recommended events for different types of apps, all appearing at the top of the Events table within the Firebase project. While GA displays three recommendations by default, the additional recommendations can be viewed by selecting Show All.
Similar to GA4 web property events, GA for Firebase supports a set of automatically-collected events and recommended events, along with predefined user dimensions. To create events for an app, the starting point is installing GA for Firebase SDK, then reference “Log events” in the Firebase documentation for details on setting up specific events.
Once the SDK is installed, however, you can add Tag Manager to your app and remotely configure events and parameters within Tag Manager (GTM).
Ecommerce Event Migration
The best practice for ecommerce migration is to leave the UA implementation alone and build duplicate events in GA4. As noted above in the Dual Tagging section, multiple methods exist to maintain UA tracking and reporting while implementing GA4 ecommerce events. Reference the specific options for gtag.js and GTM in the GA Developer resources for ecommerce migration.
Predefined events are the first components of an ecommerce migration. These recommended events take advantage of GA’s automatically populated dimensions and metrics, GAs predefined calculations, and the resulting insights not available when defining your own custom events. Recommended ecommerce events feed into GA4’s monetization reports and support the measuring steps of an ecommerce funnel as well.
Online Sales Recommended Events
Create ecommerce events in GA4, following first the recommended events, including predefined online sales events. Only after mapping against and creating recommended events should existing UA ecommerce events be created as a custom event. Creating a recommended ecommerce event, such as "add_to_cart," follows the same process as all other recommended events.
Ecommerce Parameters
Always use the required names for e-commerce events and parameters. Clicking any event name in the Online Sales events table in GA support links directly to the predefined parameters. For example, clicking "add_to_cart" in the table brings up the associated parameters below.
