This document provides an overview of some of the advanced configuration features of the Google Analytics SDK for iOS v3.
Overview
The Google Analytics SDK for iOS provides a
GAITracker
class to
set and send data to Google Analytics, and a
GAI
singleton
that serves as an interface to the global configuration values of your
implementation.
Initialization
Before any data can be measured, you must initialize at least one tracker
via GoogleAnalytics
singleton by providing a
name for the tracker
and a Google Analytics property ID:
// Initialize a tracker using a Google Analytics property ID. [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];
Now this tracker can be used for setting and sending data to Google Analytics.
Setting and Sending Data
Data is sent to Google Analytics by setting maps of parameter-value
pairs on the tracker and sending them via the set
and send
methods:
/* * Send a screen view to Google Analytics by setting a map of parameter * values on the tracker and calling send. */ // Retrieve tracker with placeholder property ID. id<GAITracker> tracker = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"]; NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys: @"appview", kGAIHitType, @"Home Screen", kGAIScreenName, nil]; [tracker send:params];
The
GAIDictionaryBuilder
class
simplifies the process of building hits and is recommended for most use
cases. Here we can send the same screen view with fewer lines of code:
// Previous V3 SDK versions. // Sending the same screen view hit using [GAIDictionaryBuilder createAppView] // [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen" // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. // Sending the same screen view hit using [GAIDictionaryBuilder createScreenView] [tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]];
Measurement Protocol Ampersand Syntax
Values may also be set on a single hit, by setting the value on a Builder
, or on
all subsequent hits, by setting it on the tracker object itself, using the Measurement Protocol
ampersand syntax:
// Sending the same screen view hit using ampersand syntax. // Previous V3 SDK versions. // [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen" // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]];
For the complete list of available measurement protocol parameters, see the Measurement Protocol Parameter Reference.
Applying Values to Multiple Hits
Any values set on the tracker directly will be persisted and applied to multiple hits, as in this example:
// May return nil if a tracker has not yet been initialized with // a property ID. id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; // Set screen name on the tracker to be sent with all hits. [tracker set:kGAIScreenName value:@"Home Screen"]; // Send a screen view for "Home Screen". // [tracker send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [tracker send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up. // This event will also be sent with &cd=Home%20Screen. [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"UX" action:@"touch" label:@"menuButton" value:nil] build]]; // Clear the screen name field when we're done. [tracker set:kGAIScreenName value:nil];
Only values that you want to persist across multiple hits should be set directly on the tracker. Setting a screen name on a tracker would make sense, since the same value can be applied to subsequent screen view and event hits. However, it is not recommended to set a field like hit type on the tracker, because it will likely change with each hit.
Using Multiple Trackers
Multiple trackers may be used in a single implementation, which can be useful for sending data to multiple properties:
id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"]; // Trackers may be named. By default, name is set to the property ID. id<GAITracker> t2 = [[GAI sharedInstance] trackerWithName:@"altTracker" trackingId:@"UA-XXXX-2"]; [t1 set:kGAIScreenName value:@"Home Screen"]; [t2 set:kGAIScreenName value:NSStringFromClass([self class])]; // Send a screenview to UA-XXXX-1. // [t1 send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [t1 send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up. // Send a screenview to UA-XXXX-2. // [t2 send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [t2 send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up.
Automated measurement features, like automatic screen and uncaught exception measurement, will only use one tracker to send data to Google Analytics. If you are using these features and want to send data using other trackers, you will need to do so manually.
For reference, automatic screen measurement uses the tracker specified in the
tracker
property of a given GAITrackedViewController
.
Uncaught exception measurement uses the default tracker specified in your
GAI
instance.
Using the Default Tracker
Google Analytics maintains a default tracker. The first tracker initialized becomes the default tracker but may be overridden:
// t1 becomes the default tracker because it is the first tracker initialized. id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"]; id<GAITracker> t2 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-2"]; // Returns t1. id<GAITracker> defaultTracker = [[GAI sharedInstance] defaultTracker]; // Hit sent to UA-XXXX-1. // Previous V3 SDK versions. // [defaultTracker send:[[[GAIDictionaryBuilder createAppView] // set:@"Home Screen" forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [defaultTracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]]; // Override the default tracker. [[GAI sharedInstance] setDefaultTracker:t2]; // Returns t2. defaultTracker = [[GAI sharedInstance] defaultTracker]; // Hit sent to UA-XXXX-2. // Previous V3 SDK versions. // [defaultTracker send:[[[GAIDictionaryBuilder createAppView] // set:NSStringFromClass([self class]) // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [defaultTracker send:[[[GAIDictionaryBuilder createScreenView] set:NSStringFromClass([self class]) forKey:kGAIScreenName] build]];
Sampling
You can enable client-side sampling to limit the number of hits sent to Google Analytics. If your app has a large number of users or otherwise sends a large volume of data to Google Analytics, enabling sampling will help ensure un-interrupted reporting.
For example, to implement client-side sampling at a rate of 50%, use the following code:
// Assumes a tracker has already been initialized with a property ID, otherwise // getDefaultTracker returns nil. id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; // Set a sample rate of 50%. [tracker set:kGAISampleRate value:@"50.0"];
App-level Opt Out
You can enable an app-level opt out flag that will disable Google Analytics
across the entire app. Note that this flag must be set each time the app starts
up and will default to NO
.
To get the app-level opt out setting, use:
// Get the app-level opt out preference. if ([GAI sharedInstance].optOut) { ... // Alert the user they have opted out. }
To set the app-level opt out, use:
// Set the app-level opt out preference. [[GAI sharedInstance] setOptOut:YES];
Delete client-side user data
If you need to reset or delete Google Analytics client-side data for your end users you can delete the Google Analytics files or set a new Client Id.
Option 1: Delete the Google Analytics files
If your app does not explicitly set the Client Id for an end user then you can force the generation of a new Client Id by deleting the Google Analytics files used to store the Client Id.
The following example method can be used to to delete the Google Analytics files. The method must be executed prior to initializing Google Analytics:
/* Execute this before [GAI sharedInstance] is initialized. */ static void DeleteGAFiles(void) { NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES); NSFileManager *fileManager = [NSFileManager defaultManager]; NSArray *libraryFiles = [fileManager contentsOfDirectoryAtPath:paths.firstObject error:nil]; NSPredicate *predicate = [NSPredicate predicateWithFormat:@"self BEGINSWITH 'googleanalytics'"]; NSArray *matchingFileNames = [libraryFiles filteredArrayUsingPredicate:predicate]; for (NSString *fileName in matchingFileNames) { NSError *error; NSString *filePath = [paths.firstObject stringByAppendingPathComponent:fileName]; if (![fileManager removeItemAtPath:filePath error:&error]) { // Log error. } } }
Option 2: Set a new Client Id
You can generate and set a new unique Client Id. All subsequent hits will use the new Client Id and prior data will not be associated with the new Client Id.
Execute the following code to generate and set a new Client Id:
[GAI sharedInstance].optOut = YES; // This Id should be a valid UUID (version 4) string as described in https://goo.gl/0dlrGx. NSString *newClientID = [NSUUID UUID].UUIDString.lowercaseString; id dispatcher = [[GAI sharedInstance] performSelector:@selector(dispatcher)]; id dataStore = [dispatcher performSelector:@selector(dataStore)]; if ([dataStore respondsToSelector:@selector(setClientId:)]) { [dataStore performSelector:@selector(setClientId:) withObject:newClientID]; } [GAI sharedInstance].optOut = NO;
Anonymize IP
Enabling anonymize IP functionality tells Google Analytics to anonymize the IP information sent by the SDK by removing the last octet of the IP address prior to its storage.
The following example shows how to enable the anonymize IP functionality for a tracker:
[tracker set:kGAIAnonymizeIp value:@"1"];
Anonymize IP functionality can be set at any time.
Testing and Debugging
The Google Analytics SDK for iOS provides tools to make testing and debugging easier.
Dry Run
The SDK provides a dryRun
flag that when set, prevents any
data from being sent to Google Analytics. The dryRun
flag should be set
whenever you are testing or debugging an implementation and do not want test data to
appear in your Google Analytics reports.
To set the dry run flag:
[[GAI sharedInstance] setDryRun:YES];
Logger
The
GAILogger
protocol is
provided to handle useful messages from the SDK at these levels of verbosity:
error
, warning
, info
, and verbose
.
The SDK initializes a standard Logger
implementation, which
by default will only log warning or error messages
to console. To set the verbosity of the Logger
:
// Set the log level to verbose. [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
Custom implementations of Logger
can also be used:
// Provide a custom logger. [[GAI sharedInstance].logger = [[CustomLogger alloc] init];
Complete Example
The example below shows the code required to initialize a Google Analytics implementation and send a single screen view.
Next, a screen view is measured when the first screen is displayed to a user:
Typically the initialization of an implementation can be done from the app delegate, as in this example:
// // AppDelegate.h // #import <UIKit/UIKit.h> #import "GAI.h" @interface AppDelegate : UIResponder <UIApplicationDelegate> @property (strong, nonatomic) UIWindow *window; @property (strong, nonatomic) id<GAITracker> tracker; @end // // AppDelegate.m // #import "AppDelegate.h" /** Google Analytics configuration constants **/ static NSString *const kGaPropertyId = @"UA-XXXX-Y"; // Placeholder property ID. static NSString *const kTrackingPreferenceKey = @"allowTracking"; static BOOL const kGaDryRun = NO; static int const kGaDispatchPeriod = 30; @interface AppDelegate () - (void)initializeGoogleAnalytics; @end @implementation AppDelegate - (void)applicationDidBecomeActive:(UIApplication *)application { [GAI sharedInstance].optOut = ![[NSUserDefaults standardUserDefaults] boolForKey:kTrackingPreferenceKey]; } - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Do other work for customization after application launch // then initialize Google Analytics. [self initializeGoogleAnalytics]; return YES; } - (void)initializeGoogleAnalytics { [[GAI sharedInstance] setDispatchInterval:kGaDispatchPeriod]; [[GAI sharedInstance] setDryRun:kGaDryRun]; self.tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId]; } // The rest of the app delegate code omitted. @end
Then, to measure a screen view when a view is displayed to a user:
// // MyViewController.m // #import "MyViewController.h" #import "AppDelegate.h" #import "GAI.h" #import "GAIFields.h" #import "GAITracker.h" #import "GAIDictionaryBuilder.h" @implementation MyViewController - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; // This screen name value will remain set on the tracker and sent with // hits until it is set to a new value or to nil. [[GAI sharedInstance].defaultTracker set:kGAIScreenName value:@"Home Screen"]; // Send the screen view. // Previous V3 SDK versions. // [[GAI sharedInstance].defaultTracker // send:[[GAIDictionaryBuilder createAppView] build]]; // SDK Version 3.08 and up. [[GAI sharedInstance].defaultTracker send:[[GAIDictionaryBuilder createScreenView] build]]; }