Important: This document describes a legacy version of the SDK. New users should use the latest SDK.

Custom Dimensions & Metrics - Android SDK

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

Overview

Custom dimensions enable the association of metadata with hits, users, and sessions in Google Analytics, while custom metrics enable you to create and increment your own metrics in Google Analytics.

  1. Configure the custom dimension or metric using the Google Analytics web interface. Learn how to configure a custom dimension or metric (Help Center).
  2. Set and send custom dimension and metric values from an app.

Custom dimensions and metrics consist of two fields:

  • Integer Index – the index of the custom dimension or metric. This index is 1-based.
  • String Value – the value of the custom dimension or metric. In this case of metrics, will be parsed as an integer, or a fixed point decimal value, if the metric is configured to a currency type.

Setting and Sending Values

To set and send a custom dimension value:

// May return null if EasyTracker has not yet been initialized with a
// property ID.
EasyTracker easyTracker = EasyTracker.getInstance();

// Send the custom dimension value with a screen view.
// Note that the value only needs to be sent once, so it is set on the Map,
// not the tracker.
easyTracker.send(MapBuilder
    .createAppView("Home screen")
    .set(Fields.customDimension(1), "premiumUser");
    .build()
);

Custom dimension values can be sent with any Google Analytics hit type, including screen views, events, ecommerce transactions, user timings, and social interactions. The defined scope of the custom dimension will determine, at processing time, which hits are associated with the dimension value.

To set and send a custom metric value:

// May return null if EasyTracker has not yet been initialized with a
// property ID.
EasyTracker easyTracker = EasyTracker.getInstance();


// Set the custom metric to be incremented by 5 using its index.
easyTracker.set(Fields.customMetric(1), 5);


// Custom metric value sent is with this screen view.
easyTracker.send(MapBuilder
    .createAppView("Home screen")
    .build()
);

Implementation Considerations

This section outlines additional considerations to keep in mind when implementing custom dimensions or metrics.

Considerations for Custom Dimensions

Values with User and Session-Level Scopes Apply to Past Hits

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

Considerations for Custom Metrics

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.

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, manual screen measurement is recommended 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.