This developer guide describes how to use the Google Analytics SDK v4 for Android to implement custom dimensions and metrics.
- Use the Google Analytics web interface to configure the custom dimension or metric. Learn how to configure a custom dimension or metric (Help Center).
- Set and send custom dimension and metric values from an app.
Custom dimensions and metrics consist of two fields:
||Index of the custom dimension or metric. This index is 1-based.|
||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:
// Get tracker. Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker( TrackerName.APP_TRACKER); t.setScreenName("Home Screen"); // Send the custom dimension value with a screen view. // Note that the value only needs to be sent once. t.send(new HitBuilders.ScreenViewBuilder() .setCustomDimension(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:
// Get tracker. Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker( TrackerName.APP_TRACKER); t.setScreenName("Home Screen"); // Send the custom dimension value with a screen view. // Note that the value only needs to be sent once. t.send(new HitBuilders.ScreenViewBuilder() .setCustomMetric(1, 5) .build() );
Advanced Configuration for details on the
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
1to 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
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.