This guide describes how to upgrade to V3 of the Google Analytics SDK for iOS.
At a Glance: What's New in V3
APIs in V3 have been refactored to be more consistent across native and web platforms. All V2 users should note these changes:
- Hits are now sent using a single
send:(NSDictionary *)params
method. - Automatic Client-side session management has been removed. Session timeout can be configured in the management interface instead. Learn more.
- Debug mode has been replaced with a
Logger
- New: A
dryRun
flag has been added to prevent dispatched data from appearing in reports. - New: Support for local currencies has been added for iOS.
For the complete list of changes, see the Changelog.
Before you Begin
Before beginning the upgrade to v3, you will need the following:
Upgrade Paths
To get started, select an upgrade path to v3 from your current implementation:
v1.x to v3
It is recommended that Google Analytics iOS SDK v1.x users follow the v3 Getting Started Guide to begin using v3.
v2.x to v3
v2.x users should follow these steps to upgrade to v3:
- Replace all
send<hit-type>
convenience methods with the newsend:
method:// v2 (Old) id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; [tracker sendView:@"HomeScreen"];
// v3 id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; // Set the screen name on the tracker so that it is used in all hits sent from this screen. [tracker set:kGAIScreenName value:@"Home Screen"]; // Send a screenview. // [tracker send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [tracker send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up.
- Automatic, client-side session management has been removed in v3. The session
timeout period can be set in the management interface and defaults to 30 minutes.
Sessions can also be started and stopped manually using the
sessionControl
parameter. Learn more about session management in v3. - Users of
Automatic Screen Tracking should replace references to
GAITrackedViewController.trackedViewName
withGAITrackedViewController.screenName
:// v2 (Old) #import "GAITrackedViewController.h" @implementation AboutViewController - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; self.trackedViewName = @"About Screen"; } // ... Rest of ViewController implementation.
// v3 #import "GAITrackedViewController.h" @implementation AboutViewController - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; self.screenName = @"About Screen"; } // ... Rest of ViewController implementation.
- Debug mode is deprecated -- use
Logger
instead:// v2 (Old) [GAI sharedInstance].debug = YES;
// v3 [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
- The
GAI.useHttp
property has been removed -- to send hits using HTTP instead of the default HTTPS, set thekGAIUseSecure
param on eachGAITracker
instead:// v2 (Old) // AppDelegate.m #import AppDelegate.h #import GAI.h - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { static NSString const *kGaPropertyId = @"UA-XXXX-Y"; id
tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId]; // Send hits using HTTP (default=HTTPS). tracker.useHttps = NO; } // v3 // AppDelegate.m #import AppDelegate.h #import GAI.h - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { static NSString const *kGaPropertyId = @"UA-XXXX-Y"; id
tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId]; // Send hits using HTTP (default=HTTPS). [tracker set:kGAIUseSecure value:[@NO stringValue]]; } - The v3 SDK no longer automatically starts a new session when the app opens. If you want to preserve this behavior from v2, you need to implement your own session control logic when a user starts the app:
- The app-level opt out setting is no longer persisted by the SDK and must be
set each time the app is launched (defaults to
NO
). Learn more about setting the Application-level opt out.
// AppDelegate.m #import AppDelegate.h #import GAI.h - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { static NSString const *kGaPropertyId = @"UA-XXXX-Y"; idtracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId]; // CAUTION: Setting session control directly on the tracker persists the // value across all subsequent hits, until it is manually set to null. // This should never be done in normal operation. // // [tracker set:kGAISessionControl value:@"start"]; // Instead, send a single hit with session control to start the new session. [tracker send:[[[GAIDictionaryBuilder createEventWithCategory:@"UX" action:@"appstart" label:nil value:nil] set:@"start" forKey:kGAISessionControl] build]];
Reference
The following sections provide reference examples of how to set and send data using the V3 SDK.
Sending Data using Dictionaries in v3
In V3, data is sent using a single
send:
method that takes
an NSDictionary
of Google
Analytics fields and values as an argument. A
GAIDictionaryBuilder
utility class is provided to
simplify the process of building hits:
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; [tracker set:kGAIScreenName value:@"Home Screen"]; // Previous V3 SDK versions. // [tracker send:[[GAIDictionaryBuilder createAppView] setValue:@"Premium" // Creates a Map of hit type 'AppView' (screenview) and set any additional fields. // forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method. // SDK Version 3.08 and up. [tracker send:[[GAIDictionaryBuilder createScreenView] setValue:@"Premium" // Creates a Map of hit type 'ScreenView' and set any additional fields. forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.
The
GAIDictionaryBuilder
class can
be used to build any of the supported hit types, like events:
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action" // Event category (required) action:@"button_press" // Event action (required) label:@"play" // Event label value:nil] build]]; // Event value
Learn more about Sending Data in v3.
Setting Data on the Tracker in v3
Values may also be set directly on a
GAITracker
using the
set:value:forKey
method.
Values set directly are applied to all subsequent hits from that
GAITracker
:
// Values set directly on a tracker apply to all subsequent hits. [tracker set:kGAIScreenName value:@"Home Screen"]; // This screenview hit will include the screen name "Home Screen". // [tracker send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [tracker send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up. // And so will this event hit. [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action" action:@"button_press" label:@"play" value:nil] build]];
To clear a value that's been set on the
GAITracker
, set the property
to nil
:
// Clear the previously-set screen name value. [tracker set:kGAIScreenName value:nil]; // Now this event hit will not include a screen name value. [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action" action:@"button_press" label:@"play" value:nil] build]];