Event

Google Analytics 4, or GA4 (formerly known as “App + Web”), is a new kind of property, with different reports than what you’re used to seeing in legacy Universal Analytics (UA) and Firebase properties. GA4 is an analytics service that enables you to measure traffic and engagement across your websites and mobile apps using customizable reports. One advantage of a GA4 property is that you can use it for a website, an app, or both a website and app together. UA properties only support websites and the Firebase Console only supports native app data.

Data collection is enabled through SDK instrumentation. Once your app is properly configured, data is ingested into the mParticle platform, which maps inbound data to Google Analytics features and their required formats, and then forwards the data to Google Analytics.

Setup Steps

You will need a GA4 account and an app property for every app that you want to track. To set that up, follow Google’s instructions here. mParticle supports sending data to GA4 via web, native iOS and Android apps, and server to server. Each platform will require a data stream. See Google’s documentation for how to create a GA4 data stream.

On mParticle you need to create a new Configuration. To do so, find Google Analytics 4 on the Directory, click on Setup, give your new Configuration a name and decide if you want the same credentials for Development and Production. Finally click Save.

Web

Data can be sent to GA4 via Web both client and server side. If you are self hosting, you can import either @mparticle/web-google-analytics-4-client-kit or @mparticle/web-google-analytics-4-server-kit depending on your use case. Note that if you want to send data server side, you must import the server kit AND enable Forward Web Requests Server Side. Enabling this setting and importing the client side kit will not work.

A GA4 Measurement ID is automatically generated when a web data stream is added. To find your Measurement ID, see here. Our GA4 web integration allows you to send your web data both client and server side.

Sending Data via Web Client Side

To send data client side on web, simply create a new Google Analytics 4 output in the mParticle UI and add it as a Connected Output to the Web Input. Add the Measurement ID to the appropriate field in the GA4 Connection Settings in the mParticle UI. Sending data server side requires mParticle to load Google’s GA4 web SDK (gtag.js).

Sending Data via Web Server Side

As required by the Google API, you must use the GA4 SDK for server-side integration. mParticle supports forwarding with both a client-side kit to forward to GA4 as well as S2S to the GA4 Measurement Protocol API. However, both have requirements that require the GA4 SDK be integrated natively. If you turn on the GA4 integration in our UI AND are using the mParticle web SDK, mParticle does this for you. If you want to forego the web SDK altogether, you must include the GA4 SDK yourself (GA4 docs). If you are currently forwarding data S2S to mParticle’s Events API, you must update the payloads to support forwarding to GA4, which requires the GA4 SDK to grab the relevant client_id.

You may prefer to send web data server side in order to reduce both the the number of calls the browser makes, and the size of your web site. In this scenario, events are sent to mParticle’s servers, and then forwarded from mParticle’s servers to GA4.

To send data server side, check Forward Requests Server Side in the Connection Settings. Add the Measurement ID and you will also need to include a Measurement Protocol API Secret. On GA4, each data stream can have one or more Measurement Protocol API Secrets. To create one:

1. Locate your data stream where you viewed your Measurement ID from above.
2. Click on Measurement Protocol API Secrets
3. Click Create.
4. Provide a Nickname, and click Create again.
5. Copy the newly generated Secret value and paste it into the mParticle setting into the mParticle connection setting for GA4.

Sending Data via Web Server Side with the mParticle web SDK

Google’s server side API for GA4 requires a client_id which still necessitates loading Google’s Global Site Tag (gtag.js), but our web SDK automatically loads gtag.js for you. mParticle sends the client_id to our servers which then forward to Google server side.

Sending Data via Web Server Side without the mParticle web SDK

Optionally, if you are not using the mParticle web SDK, you can resolve the client_id by directly calling the Global site tag API.

When the payload is sent to our endpoint, it will require to have the client_id as part of the integration attributes under the key 160 as the following example:

"integration_attributes": {
    "160": {
        "client_id": "your_client_id"
    }
},

Native

You can set up your native app to process GA4 data client side from your users’ devices.

Add the Kit

mParticle’s GA4 integration requires that you add the mParticle GA4 Kit to your iOS or Android app.

mParticle publishes the GA4 kit as separate iOS and Android libraries which have a transitive dependency on the mParticle core libraries. You can add them to your app via Carthage, Cocoapods, or Gradle:

use_frameworks!
target '<Your Target>' do
    pod 'mParticle-Google-Analytics-Firebase-GA4'
end

dependencies {
    // Ensure the Kit version matches that of the mParticle Core SDK that you're using
    compile 'com.mparticle:android-googleanalyticsfirebasega4-kit:VERSION'
}

Reference the Apple SDK and Android SDK guides to read more about kits.

Sending Data via Native Apps Client Side

Firebase is still used to send data client side to GA4. As a result, there are several references to Firebase and Firebase docs throughout this page.

Before GA4, mobile data was analyzed within the Firebase Console. If you have a legacy Firebase property, Google provides step by step instructions to upgrade a Firebase instance so that data will also flow to GA4. After upgrading, your mobile data will be available for analyzing within the GA4 dashboard alongside web data. Once your Firebase properties are upgraded to GA4, the data will show up in both the Firebase Console as well as the GA4 console.

To send data to GA4 client side in an app, first add a platform-specific data stream`

1. Follow the steps here under “Add a data stream” to create a data stream for Android or iOS. These instructions include downloading either the google-services.json for Android, or the GoogleService-Info.plist for iOS.
2. Set up Google Analytics for Firebase as an output and connect it to iOS or Android in the mParticle UI.
3. Add the mParticle Firebase kit to your app (see platform-specific docs for adding kits for iOS and Android).

Android

Due to a known issue in the Firebase Android SDK, it is impossible to programatically initialize Firebase at runtime - you must follow the Firebase documentation for adding Firebase to your application. mParticle will be tracking this issue and if it is resolved, the integration will be updated to support runtime initialization.

The Firebase-GA4 kit will detect if you have initialized Firebase, and use the existing instance in your app if present. Despite this, all typical mParticle controls such as data filtering and user-filtering are available as expected to protect the flow of event data from mParticle to GA4. However, by directly including the Firebase SDK and configuration files in your app, mParticle cannot prevent it from collecting other data automatically.

Please see Firebase’s Android setup guide here.

iOS

Our iOS implementation also requires you to manually instrument and initialize the Firebase SDK. Data will be automatically forwarded to that instance - mParticle will not create an additional instance.

You must follow the Firebase docs to create a Firebase project and download your GoogleService-Info.plist configuration file. You must then include the plist directly in your app.

Please see Firebase’s iOS setup guide here.

Sending Data via Native Apps Server Side

You may prefer to send this data server side in order to reduce both the the number of calls the device makes, and the size of your app. In this scenario, events are sent to mParticle’s servers, and then forwarded from mParticle’s servers to GA4.

To send data server side, check Forward Requests Server Side in the Connection Settings. You will also need to include your Firebase App ID and a Measurement Protocol API Secret to forward web requests server side. Each data stream can have one or more Measurement Protocol API Secret. To create one:

1. locate your data stream where you viewed your Firebase App ID and then:
2. Click on Measurement Protocol API Secrets
3. Click Create.
4. Provide a Nickname, and click Create again.
5. Copy the newly generated Secret value and paste it into the mParticle setting into the mParticle connection setting for GA4.
6. Copy the Firebase App ID from the Data Stream details page into the connection settings as well.

Sending Data via Native Apps Server Side with the kit

Google’s server side API for GA4 requires an app_instance_id which comes from the Firebase SDK. The mParticle Firebase for GA4 kit automatically sends the app_instance_id to our servers to then forward to Google. This means you will need to include the mParticle Firebase Kit and Firebase SDK in your app.

Sending Data via Native Apps Server Side without the kit

Optionally, you can resolve the app_instance_id by directly calling the Firebase SDK. When the payload is sent to our endpoint, it will require the app_instance_id as part of the integration attributes under the key 160 as the following example:

"integration_attributes": {
    "160": {
        "app_instance_id": "your_app_instance_id"
    }
},

Feeds

When connecting a feed, you’ll need to specify an app_instance_id or client_id value in the Firebase App ID/Measurement ID setting, and select which ID it corresponds to in the ID Type setting.

Other Platforms

Because Google has the requirement for either the app_instance_id or the client_id property in all requests, which come from Google’s SDKs, we are not supporting any other platforms at the time. We are working closely with Google to support other platforms when they provide a strategy that doesn’t require an SDK.

Data Processing Notes

While mParticle forwards all data in real time, GA4 has different processing times depending on the data your are sending. See the Google documentation for more information on latency and data limits.

GA4 has limits around the number of custom dimensions and custom metrics as noted here.

Migrating to Google Analytics 4

Depending on if you are migrating from a web or a native property, there are different considerations.

Migrating from the mParticle’s Legacy Google Analytics Web Kit

From a code perspective, there are a few changes you will need to make when migrating from UA to GA4. You may want to familiarize yourself with the differences between GA4 and UA by reading Google’s in-depth comparison here.

Specifically, a few core changes Google made from UA to GA4 that impact our kits are as follows:

• UA supports 5 potential content groups. GA4 uses event scoped custom dimensions to map these old content groups.
• UA supports non-interaction flags. GA4 drops this support.
• UA supports Category, Action, and Label. GA4 drops this support.
• UA supports User Timing. GA4 drops this support.
• UA supports Hit Types. All events in GA4 are considered Events. GA4 does not support Hit Types.

All of the associated custom flags related to the above are no longer relevant and should not be included when implementing mParticle’s GA4 web kit.

Migrating from mParticle’s Legacy Native Firebase Kits

Because the GA4 data model is driven by Firebase, no changes are needed to keep your current code working. However, we did add additional support for new GA4 ecommerce events: add_shipping_info and add_payment_info. See Custom Flags for more information.

The Firebase event select_content is select_item in GA4.

Recommended Events and Parameters

Google can auto-generate reports based on recommended event names and recommended event parameters when sent to GA4. You may already have a data model that does not line up exactly with GA4’s new recommended event names and parameters. As such, mParticle and Google’s UIs allow you to map data being sent to them to match Google’s data model for recommended events. Note that mParticle automatically maps commerce events for you, though you may want to customize the mapping.

Depending on your use case, mapping mParticle events to Google’s recommended events is done in either the mParticle UI or the Google UI.

Client-Side Event and Parameter Mapping Modifications (Google UI)

Google specifies in their documentation that modifications in their UI are executed client side before the data reaches Google. Additionally, modifications are generally updated within an hour, but may possibly take longer to take effect. The following is a summary of how to set up event modifications:

1. In the left pane, click Configure, then Events
2. Click Modify event or Create event
3. If your property has more than one data stream, you will be asked to select a data stream
4. Click Create and follow Google’s docs to modify an event or parameter.

Server-Side Event and Parameter Mapping Modifications (mParticle UI)

Google’s UI does not support modifications to their server. However, our Custom Mappings feature does support mapping event names and parameters server-side.

Troubleshooting

If you don’t see data in your GA4 UI, there could be a couple of issues:

1. Your payload does not adhere to GA4 standards. Google has strict payload limitations around number of parameters, user properties, etc. These limitations can be found here.
2. For eCommerce events, if a revenue amount is included, Google requires a currency code.
3. All transaction IDs should be unique, or they will be de-duplicated by Google.

GA4 Mapping

User Id Mapping

You can configure the integration to automatically map the following identities to GA4:

• Customer ID
• mParticle ID
• Other-Other10

User Attributes Mapping

mParticle will map user attributes to GA4.

Event Mapping

Custom events

mParticle forwards all custom events including the event name and any custom attributes to the Firebase logEvent API.

Screen events

Kit integrations automatically invoke setScreen APIs for every screen event passed through mParticle.

Event Attributes

The following Firebase attributes are automatically be mapped to the equivalent mParticle attribute for Commerce events.

• coupon
• currency
• item_brand
• item_category
• item_id
• item_location_id
• item_name
• item_list
• item_variant
• price
• quantity
• shipping
• tax
• transaction_id
• value

Commerce events

mParticle automatically maps commerce events to Firebase event names based on the product action.

Custom Flags

Custom flags are used to send partner-specific data points:

Add Shipping Info Custom Flag Example

To map to a Firebase add_shipping_info event, pass a custom flag of GA4.CommerceEventType equal to add_shippping_info and an optional custom flag of GA4.ShippingTier with a string value. The following examples show constants being used for iOS and Android:

import com.google.firebase.analytics.FirebaseAnalytics;
import com.mparticle.kits.GoogleAnalyticsFirebaseGA4Kit;

CommerceEvent event = new CommerceEvent.Builder(Product.CHECKOUT_OPTION, new Product.Builder("Spa Essentials", "spa-1", 100.00).build())
                .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_SHIPPING_INFO)
                .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_SHIPPING_TIER, "overnight")
                .build();
MParticle.getInstance.logEvent(event);

import com.google.firebase.analytics.FirebaseAnalytics

val event = CommerceEvent.Builder(Product.CHECKOUT_OPTION, Product.Builder("Spa Essentials", "spa-1", 100.00).build())
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_SHIPPING_INFO)
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_SHIPPING_TIER, "overnight")
    .build()
MParticle.getInstance().logEvent(event)

@import mParticle_Apple_SDK;
@import mParticle_Google_Analytics_Firebase_GA4;
@import FirebaseAnalytics;

MPProduct *product = [[MPProduct alloc] initWithName:@"Spa Essentials" sku:@"spa-1" quantity:@1 price:@100.00];
MPCommerceEvent *event = [[MPCommerceEvent alloc] initWithAction:MPCommerceEventActionCheckoutOptions product:product];
[event addCustomFlag:kFIREventAddShippingInfo withKey:kMPFIRGA4CommerceEventType];
[event addCustomFlag:@"overnight" withKey:kMPFIRGA4ShippingTier];
[[MParticle sharedInstance] logEvent:event];

import mParticle_Apple_SDK
import mParticle_Google_Analytics_Firebase_GA4
import FirebaseAnalytics

let product = MPProduct(name: "Spa Essentials", sku: "spa-1", quantity: 1, price: 100.0)
let event = MPCommerceEvent(action: .checkoutOptions, product: product)
event.addCustomFlag(AnalyticsEventAddShippingInfo, withKey: kMPFIRGA4CommerceEventType)
event.addCustomFlag("overnight", withKey: kMPFIRGA4ShippingTier)
MParticle.sharedInstance().logEvent(event)

const product1 = mParticle.eCommerce.createProduct(
    'Spa Essentials',  // Name
    'spa-1',           // SKU
    100.00,            // Price
    4                  // Quantity
);
const customAttributes = {sale: true};
const customFlags = {
  'GA4.CommerceEventType': 'add_shipping_info',
  'GA4.ShippingTier': 'overnight'
};
mParticle.eCommerce.logProductAction(
  mParticle.ProductActionType.CheckoutOption,
    [product1],
    customAttributes,
    customFlags);

Add Payment Info Custom Flag Example

To map to a Firebase add_payment_info event, pass a custom flag of GA4.CommerceEventType equal to add_payment_info (Firebase provides a constant for this), and an optional custom flag of GA4.PaymentType with a string value:

import com.google.firebase.analytics.FirebaseAnalytics;

CommerceEvent event = new CommerceEvent.Builder(Product.CHECKOUT_OPTION, new Product.Builder("Spa Essentials", "spa-1", 100.00).build())
    // how to import GoogleAnalyticsFirebaseGA4Kit?  in the tests, it sows up as kitInstance
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_PAYMENT_INFO)
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_PAYMENT_TYPE, "Visa")
    .build();
MParticle.getInstance.logEvent(event);

import com.google.firebase.analytics.FirebaseAnalytics

val event = CommerceEvent.Builder(Product.CHECKOUT_OPTION, Product.Builder("Spa Essentials", "spa-1", 100.00).build())
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_PAYMENT_INFO)
    .addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_PAYMENT_TYPE, "Visa")
    .build()
MParticle.getInstance().logEvent(event)

@import mParticle_Apple_SDK;
@import mParticle_Google_Analytics_Firebase_GA4;
@import FirebaseAnalytics;

MPProduct *product = [[MPProduct alloc] initWithName:@"Spa Essentials" sku:@"spa-1" quantity:@1 price:@100.00];
MPCommerceEvent *event = [[MPCommerceEvent alloc] initWithAction:MPCommerceEventActionCheckoutOptions product:product];
[event addCustomFlag:kFIREventAddPaymentInfo withKey:kMPFIRGA4CommerceEventType];
[event addCustomFlag:@"visa" withKey:kMPFIRGA4PaymentType];
[[MParticle sharedInstance] logEvent:event];

import mParticle_Apple_SDK
import mParticle_Google_Analytics_Firebase_GA4
import FirebaseAnalytics

let product = MPProduct(name: "Spa Essentials", sku: "spa-1", quantity: 1, price: 100.0)
let event = MPCommerceEvent(action: .checkoutOptions, product: product)
event.addCustomFlag(AnalyticsEventAddPaymentInfo, withKey: kMPFIRGA4CommerceEventType)
event.addCustomFlag("visa", withKey: kMPFIRGA4PaymentType)
MParticle.sharedInstance().logEvent(event)

const product1 = mParticle.eCommerce.createProduct(
    'Spa Essentials',  // Name
    'spa-1',           // SKU
    100.00,            // Price
    4                  // Quantity
);
const customAttributes = {sale: true}; // if not passing any custom attributes, pass null
const customFlags = {
  'GA4.CommerceEventType': 'add_payment_info',
  'GA4.PaymentType': 'credit card'
};
mParticle.eCommerce.logProductAction(
    mParticle.ProductActionType.CheckoutOption,
    [product1],
    customAttributes,
    customFlags);

Custom Mappings

mParticle’s Google Analytics 4 integration supports custom mappings which allows you to map your events and attributes for Google Analytics 4. mParticle provides mappings for the following event types:

• add_payment_info
• add_shipping_info
• add_to_cart
• add_to_wishlist
• begin_checkout
• earn_virtual_currency
• generate_lead
• join_group
• level_up
• login
• post_score
• purchase
• refund
• remove_from_cart
• search
• select_content
• select_item
• select_promotion
• share
• sign_up
• spend_virtual_currency
• tutorial_begin
• tutorial_complete
• unlock_achievement
• view_cart
• view_item
• view_item_list
• view_promotion
• view_search_results

Custom Metrics and Custom Dimensions

Google has revamped how custom dimensions and metrics work and are implemented in GA4. From a code perspective, no more mappings between attributes and dimensions/metrics are required as with Universal Analytics. From mParticle, send events with any event attributes as normal. In Google’s UI, you can then pick the parameter and associated it with a specific custom dimension or metric. See here for how to create custom dimensions and metrics in Google’s UI.

Avoid PII in all fields

Google does not allow any data to be uploaded to Google Analytics that allows for an individual to be personally identifiable. For example, certain names, social security numbers, email addresses, or any similar data is expressly not allowed per Google Policy. Likewise, any data that permanently identifies a particular device is not allowed to be uploaded to Google (such as a mobile phone’s unique device identifier if such an identifier cannot be reset - even in hashed form).

Screen Tracking

Single-Page Web Apps

To log page views for single-page web applications, you’ll need to use our custom flags Google.Page and Google.Title to set the url and title of the page.

mParticle.logPageView(
	"Product Detail Page",
	{ page: window.location.pathname },
	{"Google.Location": window.location.pathname,
         "Google.Title": "The title of the page"}
);

Read more about logging page views through our Web SDK here.

Content Groups

In GA4, you can set a single Content Group as an event attribute content_group. See here for more info about the change in Content Groups between UA and GA4.

Connection Settings