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:
- 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. - 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. HashMapparams = 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.