Google Analytics SDK for iOS - Migrating to v3

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:

  1. Replace all send<hit-type> convenience methods with the new send: 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.
  2. 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.

  3. Users of Automatic Screen Tracking should replace references to GAITrackedViewController.trackedViewName with GAITrackedViewController.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.
  4. Debug mode is deprecated -- use Logger instead: 
    // v2 (Old)
[GAI sharedInstance].debug = YES;

    // v3
[[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
  5. The GAI.useHttp property has been removed -- to send hits using HTTP instead of the default HTTPS, set the kGAIUseSecure param on each GAITracker 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]];

}
  6. 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:
    7. // 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];

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

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]];

Learn more about Setting Data in v3