Events

This article provides guidance on how to migrate Universal Analytics (UA) events to Google Analytics 4 (GA4) events.

Since the measurement models for UA and GA4 are different, it’s recommended you rethink your data collection in terms of the GA4 model rather than port your existing UA event structure to GA4.

To learn more about GA4 events read About events.

Comparison of UA and GA4 events

Universal Analytics

For Universal Analytics (UA), measurement is carried out by sending hits. Most hit types are used to measure specific interactions (e.g. pageview) but the event hit type is available for custom/general measurement. The data sent with an event hit includes Category, Action, and Label.

Below are example Universal Analytics events for analytics.js and gtag.js libraries:

analytics.js (UA)

// Send an event using analytics.js.
ga('send', 'event', 'Settings', 'Enable', 'Dark mode');

// Alternatively, you can specify the event fields in the fieldsObject.
// The command above could be rewritten as:
ga('send', {
  hitType: 'event',
  eventCategory: 'Settings',
  eventAction: 'Enable',
  eventLabel: 'Dark mode'
});

gtag.js (UA)

gtag('event', 'Enable', {
  event_category: 'Settings',
  event_label: 'Dark mode'
});

Google Analytics 4

For Google Analytics 4 (GA4), measurement is carried out by sending events. There are events that are collected automatically, events that are predefined and recommended for you to send when appropriate, and custom events that you can send in cases where automatic or recommended events don't meet your use case.

The following is an example of a Custom event in GA4:

gtag.js (GA4)

gtag('event', 'settings_update', {
  setting: 'mode',
  status : 'dark'
});

Mapping a UA event to GA4

To migrate UA event to GA4, you need to identify if there is an equivalent GA4 event. To map a UA event to GA4 use the following stepped approach:

  1. Review the list of Automatically collected events. If a GA4 automatically collected event closely matches the UA event then remove the UA event and rely on the automatically collected event.

  2. If you did not find a match in the previous step, review the events collected via Enhanced measurement. If a GA4 enhanced measurement event closely matches the purpose of the UA event then do not migrate the UA event and instead rely on enhanced measurement to send the event. Make sure to confirm that enhanced measurement is configured correctly for your GA4 property to collect the event.

  3. If you did not find a match in the previous step, review the list of Recommended events. If a GA4 recommended event closely matches the purpose of the UA event then use the recommended event and set any applicable event parameters when sending the event.

  4. If you did not find a match in the previous step, send a Custom event.

Migration scenarios and examples

Automatically collected events

Automatically collected events are always sent and typically cannot be disabled, unless they are configurable via Enhanced measurement. In general you should not migrate UA events for which there is a sufficiently equivalent Automatically collected event.

For example, a UA event sent to measure a file download interaction would likely not need to be migrated to GA4 since the file_download event in GA4 is automatically collected.

Enhanced measurement

In general you do not need to migrate UA events to GA4 when a sufficiently equivalent GA4 event is collected via Enhanced measurement. For example, the following UA events would likely not need to be migrated to GA4 since they are already measured in GA4 via enhanced measurement:

Enhanced measurement override

If an Enhanced measurement event is equivalent in purpose to your UA event but it doesn't capture all the data you need, you can manually send the event with additional custom parameters. This requires that you configure/disable enhanced measurement for the corresponding event and manually send the GA4 event.

For example, the file_download event collected via Enhanced measurement closely matches your UA event but is missing information on the file size. To override the enhanced measurement event and include file size information, do the following:

  1. Disable File downloads in Enhanced Measurement.
  2. Wherever appropriate, manually send the file_download event with custom parameters.
    • Since the automatically collected event is disabled via enhanced measurement, you will need to manually set the parameters that would normally be collected with the event (e.g. file_extension, file_name, etc.).
  3. Create a Custom dimension/metric to see any custom parameter values in reports.

The following gtag.js example sends a GA4 file_download event with a file_size custom parameter.

gtag('event', 'file_download', {
  file_extension: '.mp4',
  file_name: 'tutorial.mp4',
  link_url: '/videos/tutorial.mp4',
  link_text: 'Download the tutorial!',

  // Custom parameter.
  file_size: '275 MB'
});

If your UA event has a sufficiently equivalent GA4 Recommended event , then migrate your UA event to the recommended event.

The following example is an analytics.js UA event to measure a login:

ga('send', 'event', 'login', 'google-sso');

The GA4 login event can be used to migrate the UA event to GA4. The GA4 gtag.js equivalent is as follows:

gtag('event', 'login', {
  method: 'google-sso'
});

Custom event

If your UA event has no corresponding Automatically collected, Enhanced measurement, or Recommended event then migrate your UA event to a custom event and create Custom dimensions and metrics as needed.

The following example shows an analytics.js UA event that measures changes to UI orientation options:

ga('send', 'event', 'orientation', 'layout', 'wide');

There is no predefined GA4 event to measure the UA event above. Instead, the following gtag.js example shows how a custom event is used to measure the same interaction in GA4:

gtag('event', 'orientation_update', {
  ui_element: 'layout',
  configuration: 'wide'
});

To include ui_element and configuration in your reports, you will need to create corresponding dimensions from these event parameters. To learn more see Custom dimensions and metrics.