Event

Google Analytics provides comprehensive analytics solutions, including event, demographic, ecommerce, funnel, crash, and exception reporting.

mParticle supports Google Analytics Mobile App Analytics through our mobile SDKs and platform forwarding functionality. Data collection is enabled through SDK instrumentation. Once your app is properly configured, it 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.

Prerequisites

If you are new to setting up Google’s Mobile App Analytics, start with Google’s Mobile App Analytics docs

When mParticle sends data server-to-server to Google Analytics, we utilize Google’s Measurement Protocol. This allows mParticle to implement server side data forwarding and supports our value proposition to customers of not requiring that additional app SDK components be continually added and updated for integrations. A Measurement Protocol overview can be found on Google’s site here: https://developers.google.com/analytics/devguides/collection/protocol/v1/

You will need a Google Analytics account and a new app property for every app that you want to track. A Google Analytics tracking id is automatically generated for each property and you will need this when configuring Google Analytics integration in the mParticle console. We are using the term “logical app” here because as a Google Analytics best practice you will want to track different physical platforms of the same app in the same property. For example, if you have an iOS app and an Android app with the same functionality that represents one logical app, but two physical apps, and as a result you would want to use the same tracking id for both. You can then setup new Google Analytics views within the same property for each app platform to have reporting by platform/physical app. If your iOS and Android apps differ significantly in terms of usage and data capture you will want to track in different properties and tracking ids.

Data Processing Notes

While mParticle forwards all data in real time, Google Analytics has a processing latency of 24-48 hours. See their documentation for more information on latency and hit limits.

Google Analytics has limits around the number of custom dimensions and custom metrics as noted here: https://support.google.com/analytics/answer/2709828#Limits

• There are 20 indices available for different custom dimensions and 20 indices for custom metrics in each property.
• Premium accounts have 200 indices available for custom dimensions and 200 for custom metrics.

If AppName is not available, then mParticle will not forward events to Google Analytics - https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an.

Supported Features

For each supported feature below, a detailed description is provided in the Supported Feature Reference Section that follows.

Client ID and User ID

One of the most important decisions to make when setting up your Google Analytics implementation is how to identify your users. Google Analytics does not allow Personally Identifiable Information to be uploaded, but you still need a unique identifier, so that you can track how many unique users you have and to keep each user’s activity separate. Google’s Measurement Protocol allows for two types of identifier:

• Client ID (cid) must be a UUIDv4.
• User ID (uid) can be any string but must not contain personally identifiable information.

AMP Connections

When configuring a configuration that will be used with AMP connections, please select AMP for the Client ID Type to ensure the best results. This will use the AMP ID when available and otherwise use the mpdevice_id field.

Client ID

There are two basic options for generating Client ID. The default is to have mParticle generate a cid for you. If you select this option, mParticle will generate a UUIDv4 for each device based on device and application metadata. This option is recommended if your app is not already being tracked in Google Analytics.

Alternatively, you can choose to use one of your Other identity types as the cid, by selecting it in the Configuration Settings. If you choose this option, you must ensure that one of the following is true:

• The identity value is a valid UUIDv4. For example, "cbc600a1-6b77-4fc5-bf20-ce9bbd2c1850".
• The identity value is a valid legacy CID and the Allow Legacy CID Format connection setting is enabled. The legacy CID format is "X.Y", where X and Y are 32-bit integers. For example, "54026365.42793867".

mParticle uses the following rules to set cid:

• If your Client ID Type is set to Default, mParticle will generate a default cid based on device and app metadata.

• If your Client ID Type is one of your Other types, mParticle will do one of the following depending on the identity value for the user.

  • If the Allow Legacy CID Format connection setting is enabled, mParticle will check whether the passed in cid is in the correct legacy format. If it is, the cid will be sent through as-is.
  • If the value of your chosen identity type is present AND a valid UUIDv4, mParticle will use that value as the cid.
  • If the value of your chosen identity type is present BUT NOT a valid UUIDv4, mParticle will generate a deterministic UUIDv4 based on the value provided.
  • If the value of your chosen identity type is not present, mParticle will generate a default cid based on device and app metadata.

User ID

mParticle gives you the option to send a hash of your Customer ID as the uid by setting Hash Customer ID in your Connection Settings.

Considerations for unbound feeds

If you are intending to send feed data from a feed which is not bound to one of your native platforms, you will need to make sure mParticle has enough information to generate at least one unique ID for each user. Without Device information, mParticle may generate the same cid value for all event data received via an unbound feed. In Google Analytics, this will look like a lot of activity from a single user. To prevent this, make sure your incoming data contains Customer ID values and set Hash Customer ID to true. When mParticle processes event data from an unbound feed with a Customer ID value, mParticle will set only a uid to prevent issues in Google Analytics that arise from multiple users having the same cid.

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).

Supported Feature Reference

This section provides detailed implementation guidance for each of the supported features.

Crashes and Exceptions

mParticle forwards events with MessageType = CrashReport to Google Analytics with the following logic:

• If logErrorEventWithException method is implemented in the app to log handled exceptions, they will be forwarded to Google Analytics accordingly.
• If beginUncaughtExceptionLogging / endUncaughtExceptionLogging methods are implemented, app crashes will be captured and forwarded to Google Analytics.

Additional Crash Handling setup can be configured for your app.

Custom Metrics and Custom Dimensions

mParticle supports 200 Custom Dimensions. You can use them to collect and analyze data that Google Analytics doesn’t automatically track. Click here for instructions on how to create custom dimensions in Google Analytics.

Once you have created the custom metrics/dimensions in Google Analytics, you can map the information in mParticle Connection settings by specifying an event attribute, a user attribute, or a product attribute.

eCommerce/Advanced eCommerce Tracking

mParticle supports both Google Analytics eCommerce and Advanced eCommerce features. In order to use the Advanced eCommerce tracking, you must enable Enhanced ECommerce Settings from the Admin section of the Google Analytics Web Interface. You must also enable the mParticle “Enable Enhanced Ecommerce” setting.

You can send in-app purchase data or any kind of transaction data to Google Analytics via eCommerce tracking. To make sure Google Analytics integration functions properly, app developers need to pass necessary information to mParticle so that mParticle can format the transaction data properly and forward it to Google Analytics.

An incoming event can have the following attributes:

Additional eCommerce Tracking Guidance

• It is important to ensure that all Google Analytics required attributes are correctly referenced. If a required attribute is missing, the eCommerce reports in Google Analytics may not be as expected.
• One product SKU is possible for each call to logEcommerceTransactionWithProduct. If your eCommerce transaction has multiple SKUs, you will need to call the method once for each SKU.
• Google Analytics enforces a max URL length of 8192 characters. Enhanced eCommerce events may be truncated if they exceed the 8192 character limit.

Event Tracking

You can associate Google Analytics custom flags with an event via the Custom Flags APIs provided by the mParticle SDKs. See the table below to determine the correct Custom Flag to append to an event for your desired Google Analytics category, label, and value. The name of the event is passed as the Event Action (Google Analytics ea parameter).

For pageview hits to be valid, either dl or both dh and dp must be set. When dl is set, its hostname and page can be overwritten using the dh and dp parameters respectively.

See the code samples below and the SDK docs for help setting custom flags with the mParticle iOS and Android SDKs.

MPEvent *event = [[MPEvent alloc] initWithName:@"Set Category"
                                          type:MPEventTypeUserPreference;

[event addCustomFlag:@"Music"
             withKey:@"Google.Category"];

[[MParticle sharedInstance] logEvent:event];

MPEvent event = new MPEvent.Builder("Set Category", MParticle.EventType.UserPreference)
                .addCustomFlag("Google.Category", "Music")
                .build();
MParticle.getInstance().logEvent(event);

mParticle maps logged events to Google Analytic’s event structure as follows:

Screen Tracking

Screens in Google Analytics represent content users are viewing within an app.

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.Page": window.location.pathname,
         "Google.Title": "The title of the page"}
);

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

Session Management

mParticle’s session management scheme will be used, which is different from Google Analytics. mParticle will forward session start and end messages to Google Analytics as follows:

Social Interactions

mParticle will forward any events with EventType = Social to Google Analytics as social events. Below is a list of attributes for social interactions that Google Analytics require and how they are mapped.

User / Event Timing

Mobile app and web developers can measure how long an event takes. On mobile this is done by passing in “eventLength” parameter to logEvent. On web, you will need to pass in a custom flag of ‘Google.UserTiming’.

Content Groups

Content Groups are only supported for client-side web data at the moment. There are multiple ways to set up Content Groups in Google’s UI, and mParticle supports setting Content Groups via tracking code. You can read more here. Google Analytics supports up to 5 Content Groups.

Sending Content Groups to Google Analytics is as simple as setting different Custom Flags at the event logging level. Content Groups can be updated and set for any event level logging (PageView, Event Logging, Commerce Event, etc) but for illustration purposes, we are logging page views below:

const customAttributes = { page: window.location.toString()};
const customFlags = {
  'Google.CG1': '/usa',
  'Google.CG2': '/sports'
  'Google.CG3': '/basketball'
  'Google.CG4': '/west'
  'Google.CG5': '/lakers'
}

mParticle.logPageView('Page Viewed', customAttributes, customFlags);

Mobile

On a logged event, if eventLength is > 0, mParticle will forward the event to Google Analytics as both an event (event hit type) and a user timing measurement (timing hit type). When forwarding as a timing hit type, the data is mapped as follows.

Since mParticle sends the data as two different hit types, two URLs are sent. For example, an event called “Update Profile” with eventLength = 1914 ms will trigger the following two URLs being sent to Google Analytics.

Event hit: https://www.google-analytics.com/collect?ec=Navigation&ea=Update+Profile&ht=1390489491362&cid=2d3636353934303434&ul=en-us&sr=1280x736&an=My+Test+App+1&av=1.4&aid=MyBundle&aiid=com.my.installer.demo&tid=UA-1234565-1&t=event&v=1&qt=380&z=9e5b1042-1a4a-49af-a247-da89951878b4

Timing hit: https://www.google-analytics.com/collect?utc=Navigation&utt=1914&utv=Update+Profile&ht=1390489491362&cid=2d3636353934303434&ul=en-us&sr=1280x736&an=My+Test+App+1&av=1.4&aid=MyBundle&aiid=com.my.installer.demo&tid=UA-1234565-1&t=timing&v=1&qt=380&z=9e5b1042-1a4a-49af-a247-da89951878b4

The ‘ec’ for the event hit types matches the ‘utc’ in timing hit type, ‘ea’ will match ‘utv’, and ‘el’ will match ‘utl’.

Web

On web, a user timing event is sent to Google Analytics when a custom flag of ‘Google.UserTiming’ is provided. The mapping to Google Analytics is as follows:

Similar to mobile, when you send a User Timing event, a regular event hit is sent as well. The following is an example that shows how an event logged to mParticle will map to both hit types:

const customAttributes = {};
const customFlags = {
  'Google.UserTiming': 1914, // required for user timing events
  'Google.Category': 'Profile' // defaults to the EventType if not provided
  'Google.Label': 'Foo-label', // optional
}

mParticle.logEvent('Update Profile', mParticle.EventType.Navigation, customAttributes, customFlags);

will map the following query parameter values to Google Analytics:

Campaign User Attribute Mapping

To handle Campaign Parameters, mParticle will forward user attributes to Google Analytics as noted below.

Configuration Settings

Connection Settings