Custom Dimensions & Metrics - Android SDK v2 (Legacy)

This developer guide describes how to implement custom dimensions and metrics using the Google Analytics SDK for Android v2.

Overview

When you set a custom dimension or metric value using the Google Analytics SDK for Android , that value is sent as a parameter with the next hit that is dispatched. Those values can be applied to any Google Analytics hit type, including screen views, events, ecommerce transactions, user timings, and social interactions.

There are two main steps to implement a custom dimension or metric:

  1. Define the custom dimension or metric using the Google Analytics web interface.
    Set the index, name, and scope of the custom dimension or metric in the property settings section of the web interface.
    Learn how to define a custom dimension or metric.
  2. Implement code to set and collect custom dimension and metric values.
    Add code to your app to set custom dimension or metric values for your Google Analytics hits at the indices you defined in the prior step.

The remainder of this article will describe how to implement the code to set and send custom dimension or metric values to Google Analytics.

Custom Dimensions

Custom dimension values can be set on all Google Analytics hit types. Set a custom dimension value just before the send call to which you want the value applied.

The defined scope of the custom dimension will determine at processing time which additional hits may be associated with that value.

These fields are required to set a custom dimension value:

  • Integer Index – the index of the custom dimension definition. This index is 1-based.
  • String Value – the value of the custom dimension.

Setting a Custom Dimension Value

To set a custom dimension value, call setCustomDimension before the send call with which you want to associate the value:

// Get the tracker object.
Tracker tracker = EasyTracker.getTracker();

// Set the dimension value for index 1.
tracker.setCustomDimension(1, "myValue");

// Dimension value is associated and sent with this hit.
tracker.sendView();

Implementation Considerations

This section outlines additional considerations to keep in mind when implementing a custom dimension.

User and Session-Level Scopes are Greedy

Custom dimension values with user or session-level scope will apply to all hits in the current session, including past hits. If you don't want a custom dimension value with session or user-level scope to be applied to past hits in the current session, start a new session before applying the value to a hit.

For example, if you're using membership type as a user-level custom dimension, and a user upgrades their membership in the middle of a session, you may want to start a new session before you set the new custom dimension value. This ensures that the hits prior to the upgrade will be associated with the old membership value, while new hits will be associated with the new value.

Custom Dimensions and View (Profile) Filters

User or session-level custom dimension values will still be applied to all hits in the current and/or future sessions even if the hit they are sent with is filtered from a view (profile).

When filtering on a custom dimension value, hits are filtered according to the scope of that custom dimension value.

Learn more about how filters and custom dimension values interact when your data is processed.

Setting Values with Automatic Screen Measurement

To apply a custom dimension value to a screen view sent via EasyTracker's automatic screen measurement, set the value before activityStart() is called during onStart().

Note that in cases where the value is not known at the time onStart() executes, it is recommended to use manual screen measurement instead.

Do not send personally identifiable information (PII) as values

The Google Analytics Terms of Service prohibit sending of any personally identifiable information (PII) to Google Analytics servers. For more information, please consult the Terms of Service.

Custom Metrics

While custom dimensions need to be carefully applied to specific hits and managed with scope, the hit to which a custom metric is applied will generally not affect reporting, and thus they can be set whenever the metric value becomes known.

These fields are required to set a custom metric value:

  • Integer Index – the index of the custom metric definition.
  • Integer Value – the value of the custom metric. Values may be negative.

Setting a Custom Metric Value

To set a custom metric value, call setCustomMetric before another send call:

// Get the tracker object.
Tracker tracker = EasyTracker.getTracker();

// Increment the metric at index 1.
tracker.setCustomMetric(1, 1);

// Metric value sent with this hit.
tracker.sendView();

Or to set a currency custom metric:

// Get the tracker.
Tracker tracker = EasyTracker.getTracker();

// Create a map for hit params.
HashMap params = new HashMap();
params.put(ModelFields.APP_SCREEN, "Product Page");

// Set currency value to custom metric slot 1.
// Currency values may be fixed decimal.
params.put("&cm1", "24.99");

// Send the custom metric value with a screen view.
tracker.send("appview", params);

Implementation Considerations

The following section outlines additional considerations to keep in mind when planning a custom dimension or metric implementation.

Custom Metric Values are Aggregated in Reports

Custom metric values are aggregated in reports just like other pre-defined metrics in Google Analytics. As a result, you would set a custom metric value of 1 to increment the metric's aggregate total in your reports.

Custom Metrics and View (Profile) Filters

Although the custom metric values can generally be set whenever is convenient, avoid setting custom metric values on hits that are likely to be filtered from your views (profiles). If a hit is filtered by a view (profile) filter, any associated custom metric values will also be filtered. Learn more about custom dimensions and metrics and view (profile) filters.