Google Analytics

Uniform enables you to add personalization and testing capabilities to your applications. Google Analytics is a popular product for capturing and reporting on activity in your application. Uniform is able to push personalization and testing data to Google Analytics, improving the reach of your analytics.

info

This analytics integration in Uniform is for GA4. The previous generation product, Universal Analytics, was deprecated on 1st July 2023.

This section describes how to activate tracking personalization and testing from Uniform in GA4. This will result in Uniform writing the following data to custom dimensions in GA4:

DimensionPersonalization eventA/B test event
Event nameAnalytics tracking name parameter from the Personalization component.Uniform test name
Event categoryUniform PersonalizationUniform AB Testing
Event labelID of the personalization variant that was displayed to the visitor.ID of the test variant that was displayed to the visitor.
Is control group1 if the visitor is a member of the control group, otherwise 0.This dimension does not apply to this event type.

In GA4, Event title and Event Category are deprecated in favor of parameters. To provide backward compatibility on tracking variants for personalization and tests on Uniform without title and category, you are required to manually create these custom dimensions for events in your Google Analytics dashboard.

  1. Log into Google Analytics.

  2. Navigate to your GA4 property.

  3. Navigate to Property settings > Data display > Custom definitions.

  4. Add the following custom dimensions:

    Dimension nameScopeEvent parameterNotes
    Event CategoryEventevent_category
    Event LabelEventevent_label
    Is Control GroupEventis_control_groupLearn more about control groups for Uniform.
    event-dimensions

The Uniform tracker can dispatch event data to Google Analytics using a plugin. You must add this plugin to your front-end application.

  1. If your application doesn't already use the Google Analytics global site tag (gtag.js), you must add the script.

    About this step

    In a web application, the global site tag must be added immediately after the head tag is closed, meaning it must be the first thing after </Head>.

  2. Add the following npm packages to your front-end application:

    @uniformdev/context-gtag

    About this step

    Make sure the package you add is version is 16.3 or greater.

  3. Add the Google Analytics plugin to the Uniform Context object.

    import { enableGoogleGtagAnalytics } from '@uniformdev/context-gtag'; ... const gaPlugin = enableGoogleGtagAnalytics({ emitAll: true }); const context = new Context({ ... plugins: [gaPlugin] }); ...

    About this step

    The Uniform Context object is passed to the tracker. The precise code used to add the tracker to your application depends on your front-end. For more information about the tracker, see the guide on how to add the Uniform tracker.

The plugin causes the tracker to fire GA4 events when Uniform
renders personalized components or variants for A/B tests on your application.

There are cases where you might want to write different data to GA4. This requires creating a custom plugin. This example demonstrates how you can do the following:

  • For personalization events, populate another custom dimension to store the hostname the visitor is interacting with.
  • For A/B test events, set the event category to "Uniform Test" (instead of "Uniform AB Testing").

A custom plugin registers (and unregisters) event listeners on the Uniform Context object. Add the following file to your front-end application.

lib/plugins.js

function onPersonalization(e) { if (typeof window === 'undefined' || !window?.gtag) return; const { control, name, variantIds } = e; variantIds.forEach((variant) => { const data = { event_category: 'Uniform Personalization', event_label: variant.id, is_control_group: control || variant.control ? 1 : 0, hostname: window.location.hostname ?? "", } window.gtag('event', name, data); }) } function onTest(e) { if (typeof window === 'undefined' || !window?.gtag) return; const { name, variantId } = e; window.gtag('event', name, { event_category: 'Uniform Test', event_label: variantId ?? '', }); } export function enableCustomGoogleGtagAnalytics() { return { init: (context => { context.events.on("personalizationResult", onPersonalization); context.events.on("testResult", onTest); return () => { context.events.off("personalizationResult", onPersonalization); context.events.off("testResult", onTest); } }) } }

The Uniform tracker can dispatch event data to Google Analytics using your custom plugin. You must add this plugin to your front-end application.

If the GA plugin is active in your application, you must remove it in order to avoid duplicate events being sent to GA4.

  1. If your application doesn't already use the Google Analytics global site tag (gtag.js), you must add the script.

    About this step

    In a web application, the global site tag must be added immediately after the head tag is closed, meaning it must be the first thing after </Head>.

  2. Add your custom plugin to the Uniform Context object.

    import { enableCustomGoogleGtagAnalytics } from "./plugins"; ... const customPlugin = enableCustomGoogleGtagAnalytics(); const context = new Context({ ... plugins: [customPlugin] }); ...

    About this step

    The Uniform Context object is passed to the tracker. The precise code used to add the tracker to your application depends on your front-end. For more information about the tracker, see the guide on how to add the Uniform tracker.

Last modified
Next
Visualize Uniform data in GA4