Custom Dimensions & Metrics - iOS SDK

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


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:

  • NSNumber Index – the index of the custom dimension or metric. This index is 1-based.
  • NSString 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 nil if a tracker has not yet been initialized with a property ID.
id tracker = [[GAI sharedInstance] defaultTracker];

// Set the custom dimension value on the tracker using its index.
[tracker set:[GAIFields customDimensionForIndex:1]
       value:@"Premium user"];

[tracker set:kGAIScreenName
       value:@"Home screen"];

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

// Previous V3 SDK versions.
// [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"premium"
//                                                   forKey:[GAIFields customDimensionForIndex:1]] build]];

// // SDK Version 3.08 and up.
[tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"premium"
                                                     forKey:[GAIFields customDimensionForIndex:1]] 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 nil if a tracker has not yet been initialized with a property ID.
id tracker = [[GAI sharedInstance] defaultTracker];

// Set the custom metric to be incremented by 5 using its index.
[tracker set:[GAIFields customMetricForIndex:1]
       value:[[NSNumber numberWithInt:5] stringValue]];

[tracker set:kGAIScreenName
       value:@"Home screen"];

// Custom metric value is sent with this screen view.
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];     // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];     // SDK Version 3.08 and up.

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 automatic screen measurement, set the value during the view controller's viewDidAppear: method. For example, your view controller's .m file might look like this:
#import "myViewController.h"
#import "GAI.h"

@implementation myViewController

    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];  // Get the tracker object.
    [tracker set:[GAIFields customDimensionForIndex:1]
    [super viewDidAppear:animated];   // Custom dimension value will be sent with the screen view.


// The remainder of the implementation is omitted.

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.