Conforms to NSObject
Declared in GAITracker.h

Overview

Google Analytics tracking interface. Obtain instances of this interface from [GAI trackerWithTrackingId:] to track screens, events, transactions, timing, and exceptions. The implementation of this interface is thread-safe, and no calls are expected to block or take a long time. All network and disk activity will take place in the background.

Tasks

  •   trackingId

    The tracking identifier (the string that begins with “UA-”) this tracker is associated with.

    property required method
  •   appName

    The application name associated with this tracker. By default, this property is populated with the CFBundleName string from the application bundle. If you wish to override this property, you must do so before making any tracking calls.

    property required method
  •   appId

    The application identifier associated with this tracker. This should be set to the iTunes Connect application identifier assigned to your application. By default, this property is nil. If you wish to set this property, you must do so before making any tracking calls.

    property required method
  •   appVersion

    The application version associated with this tracker. By default, this property is populated with the CFBundleShortVersionString string from the application bundle. If you wish to override this property, you must do so before making any tracking calls.

    property required method
  •   anonymize

    Tracking data collected while this is true will be anonymized by the Google Analytics servers by zeroing out some of the least significant bits of the IP address.

    property required method
  •   useHttps

    Tracking information collected while this is true will be submitted to Google Analytics using HTTPS connection(s); otherwise, HTTP will be used. Note that there may be additional overhead when sending data using HTTPS in terms of processing costs and/or battery consumption.

    property required method
  •   sampleRate

    The sampleRate parameter controls the probability that the visitor will be sampled. By default, sampleRate is 100, which signifies no sampling. sampleRate may be set to any value between 0 and 100, inclusive. A value of 90 means 90% of visitors should be sampled (10% of visitors to be sampled out).

    property required method
  •   clientId

    The client ID for the tracker.

    property required method
  •   appScreen

    The current screen set for this tracker.

    property required method
  •   referrerUrl

    The referrer URL for this tracker. Changing this value causes it to be sent with the next dispatch of tracking information.

    property required method
  •   campaignUrl

    The campaign URL for this tracker. This is not directly propagated to Google Analytics, but if there are campaign parameter(s), either manually or auto-tagged, present in this URL, the SDK will include those parameters in the next dispatch of tracking information. Google Analytics treats tracking information with differing campaign information as part of separate sessions.

    property required method
  •   sessionStart

    If true, indicates the start of a new session. Note that when a tracker is first instantiated, this is initialized to true. To prevent this default behavior, set this to NO when the tracker is first obtained.

    property required method
  •   sessionTimeout

    If non-negative, indicates how long, in seconds, the application must transition to the inactive or background state for before the tracker will automatically indicate the start of a new session when the app becomes active again by setting sessionStart to true. For example, if this is set to 30 seconds, and the user receives a phone call that lasts for 45 seconds while using the app, upon returning to the app, the sessionStart parameter will be set to true. If the phone call instead lasted 10 seconds, sessionStart will not be modified.

    property required method
  • – trackView

    Track that the current screen (as set in appScreen) was displayed. If appScreen has not been set, this will not generate any tracking information.

    required method
  • – trackView:

    Track that the specified view or screen was displayed. This call sets the appScreen property and generates tracking information to be sent to Google Analytics.

    required method
  • – trackEventWithCategory:withAction:withLabel:withValue:

    Track an event.

    required method
  • – trackTransaction:

    Track a transaction.

    required method
  • – trackException:withDescription:

    Track an exception.

    required method
  • – trackException:withNSException:

    Convenience method for tracking an NSException that passes the exception name to trackException:withDescription:.

    required method
  • – trackException:withNSError:

    Convenience method for tracking an NSError that passes the domain, code, and description to trackException:withDescription:.

    required method
  • – trackTimingWithCategory:withValue:withName:withLabel:

    Track user timing.

    required method
  • – trackSocial:withAction:withTarget:

    Track social action.

    required method
  • – set:value:

    Set a tracking parameter.

    required method
  • – get:

    Get a tracking parameter.

    required method
  • – send:params:

    Queue tracking information with the given parameter values.

    required method
  • – setCustom:dimension:

    Set a custom dimension value, to be sent at the next tracking call.

    required method
  • – setCustom:metric:

    Set a custom metric value, to be sent at the next tracking call.

    required method
  • – close

    Close the tracker. This will mark it as closed and remove it from the list of trackers accessible through [GAI trackerWithTrackingId:], thus decrementing its reference count (and causing it to be dealloced unless it has been retained by the application). Once this method has been called, it is an error to call any of the tracking methods, and they will not result in the generation of any tracking information to be submitted to Google Analytics.

    required method

Properties

anonymize

Tracking data collected while this is true will be anonymized by the Google Analytics servers by zeroing out some of the least significant bits of the IP address.

@property (nonatomic, assign) BOOL anonymize

Discussion

In the case of IPv4 addresses, the last octet is set to zero. For IPv6 addresses, the last 10 octets are set to zero, although this is subject to change in the future.

By default, this flag is false.

Declared In

GAITracker.h

appId

The application identifier associated with this tracker. This should be set to the iTunes Connect application identifier assigned to your application. By default, this property is nil. If you wish to set this property, you must do so before making any tracking calls.

@property (nonatomic, copy) NSString *appId

Discussion

Note that this is not your app’s bundle id (e.g. com.example.appname), but the identifier used by the App Store.

Declared In

GAITracker.h

appName

The application name associated with this tracker. By default, this property is populated with the CFBundleName string from the application bundle. If you wish to override this property, you must do so before making any tracking calls.

@property (nonatomic, copy) NSString *appName

Declared In

GAITracker.h

appScreen

The current screen set for this tracker.

@property (nonatomic, copy) NSString *appScreen

Discussion

Calling trackView: will also update this property before it dispatches tracking information to Google Analytics. However, if you wish to update the current screen without sending any tracking information, set this property directly. The updated screen will be reflected in subsequent tracking information.

Declared In

GAITracker.h

appVersion

The application version associated with this tracker. By default, this property is populated with the CFBundleShortVersionString string from the application bundle. If you wish to override this property, you must do so before making any tracking calls.

@property (nonatomic, copy) NSString *appVersion

Declared In

GAITracker.h

campaignUrl

The campaign URL for this tracker. This is not directly propagated to Google Analytics, but if there are campaign parameter(s), either manually or auto-tagged, present in this URL, the SDK will include those parameters in the next dispatch of tracking information. Google Analytics treats tracking information with differing campaign information as part of separate sessions.

@property (nonatomic, copy) NSString *campaignUrl

Discussion

For more information on auto-tagging, see http://support.google.com/googleanalytics/bin/answer.py?hl=en&answer=55590

For more information on manual tagging, see http://support.google.com/googleanalytics/bin/answer.py?hl=en&answer=55518

Declared In

GAITracker.h

clientId

The client ID for the tracker.

@property (nonatomic, copy, readonly) NSString *clientId

Discussion

This is a persistent unique identifier generated the first time the library is called and persisted unchanged thereafter. It is used to identify the client across multiple application sessions.

Declared In

GAITracker.h

referrerUrl

The referrer URL for this tracker. Changing this value causes it to be sent with the next dispatch of tracking information.

@property (nonatomic, copy) NSString *referrerUrl

Declared In

GAITracker.h

sampleRate

The sampleRate parameter controls the probability that the visitor will be sampled. By default, sampleRate is 100, which signifies no sampling. sampleRate may be set to any value between 0 and 100, inclusive. A value of 90 means 90% of visitors should be sampled (10% of visitors to be sampled out).

@property (nonatomic, assign) double sampleRate

Discussion

When a visitor is not sampled, no data is collected by Google Analytics for iOS library about that visitor’s activity. If your application is subject to heavy traffic spikes, you may wish to adjust the sample rate to ensure uninterrupted report tracking. Sampling in Google Analytics occurs consistently across unique visitors, ensuring integrity in trending and reporting even when sampling is enabled, because unique visitors remain included or excluded from the sample, as set from the initiation of sampling.

Declared In

GAITracker.h

sessionStart

If true, indicates the start of a new session. Note that when a tracker is first instantiated, this is initialized to true. To prevent this default behavior, set this to NO when the tracker is first obtained.

@property (nonatomic, assign) BOOL sessionStart

Discussion

By itself, setting this does not send any data. If this is true, when the next tracking call is made, a parameter will be added to the resulting tracking information indicating that it is the start of a session, and this flag will be cleared.

Declared In

GAITracker.h

sessionTimeout

If non-negative, indicates how long, in seconds, the application must transition to the inactive or background state for before the tracker will automatically indicate the start of a new session when the app becomes active again by setting sessionStart to true. For example, if this is set to 30 seconds, and the user receives a phone call that lasts for 45 seconds while using the app, upon returning to the app, the sessionStart parameter will be set to true. If the phone call instead lasted 10 seconds, sessionStart will not be modified.

@property (nonatomic, assign) NSTimeInterval sessionTimeout

Discussion

To disable automatic session tracking, set this to a negative value. To indicate the start of a session anytime the app becomes inactive or backgrounded, set this to zero.

By default, this is 30 seconds.

Declared In

GAITracker.h

trackingId

The tracking identifier (the string that begins with “UA-”) this tracker is associated with.

@property (nonatomic, copy, readonly) NSString *trackingId

Discussion

This property is read-only.

Declared In

GAITracker.h

useHttps

Tracking information collected while this is true will be submitted to Google Analytics using HTTPS connection(s); otherwise, HTTP will be used. Note that there may be additional overhead when sending data using HTTPS in terms of processing costs and/or battery consumption.

@property (nonatomic, assign) BOOL useHttps

Discussion

By default, this flag is false.

Declared In

GAITracker.h

Instance Methods

close

Close the tracker. This will mark it as closed and remove it from the list of trackers accessible through [GAI trackerWithTrackingId:], thus decrementing its reference count (and causing it to be dealloced unless it has been retained by the application). Once this method has been called, it is an error to call any of the tracking methods, and they will not result in the generation of any tracking information to be submitted to Google Analytics.

- (void)close

Declared In

GAITracker.h

get:

Get a tracking parameter.

- (NSString *)get:(NSString *)parameterName

Parameters

parameterName

The parameter name.

Return Value

The parameter value, or nil if no value for the given parameter is set.

Declared In

GAITracker.h

send:params:

Queue tracking information with the given parameter values.

- (BOOL)send:(NSString *)trackType params:(NSDictionary *)parameters

Parameters

trackType

The type of tracking information, e.g., @“appview”.

parameters

A map from parameter names to parameter values which will be set just for this piece of tracking information.

Return Value

YES if the tracking information was queued for submission, or NO if an error occurred (e.g. bad track type).

Declared In

GAITracker.h

set:value:

Set a tracking parameter.

- (BOOL)set:(NSString *)parameterName value:(NSString *)value

Parameters

parameterName

The parameter name.

value

The value to set for the parameter. If this is nil, the value for the parameter will be cleared.

Return Value

YES if the parameter was set to the given value, or NO if there was an error (e.g. unknown parameter).

Declared In

GAITracker.h

setCustom:dimension:

Set a custom dimension value, to be sent at the next tracking call.

- (BOOL)setCustom:(NSInteger)index dimension:(NSString *)dimension

Parameters

index

The index at which to set the dimension. Must be positive.

dimension

The dimension value, or nil if the dimension at the given index is to be cleared.

Return Value

YES on success, or NO if an error occurred.

Declared In

GAITracker.h

setCustom:metric:

Set a custom metric value, to be sent at the next tracking call.

- (BOOL)setCustom:(NSInteger)index metric:(NSNumber *)metric

Parameters

index

The index at which to set the metric. Must be positive.

metric

The metric value, which will be interpreted as a signed 64-bit integer, or nil if the metric at the given index is to be cleared.

Return Value

YES on success, or NO if an error occurred.

Declared In

GAITracker.h

trackEventWithCategory:withAction:withLabel:withValue:

Track an event.

- (BOOL)trackEventWithCategory:(NSString *)category withAction:(NSString *)action withLabel:(NSString *)label withValue:(NSNumber *)value

Parameters

category

The event category, or nil if none.

action

The event action, or nil if none.

label

The event label, or nil if none.

value

The event value, to be interpreted as a 64-bit signed integer, or nil if none.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackException:withDescription:

Track an exception.

- (BOOL)trackException:(BOOL)isFatal withDescription:(NSString *)format, ...

Parameters

isFatal

A boolean indicating whether the exception is fatal.

format

A format string that will be used to create the exception description.

...

An optional list of arguments to be substituted using the format string.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackException:withNSError:

Convenience method for tracking an NSError that passes the domain, code, and description to trackException:withDescription:.

- (BOOL)trackException:(BOOL)isFatal withNSError:(NSError *)error

Parameters

isFatal

A boolean indicating whether the exception is fatal.

error

The NSError error object.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackException:withNSException:

Convenience method for tracking an NSException that passes the exception name to trackException:withDescription:.

- (BOOL)trackException:(BOOL)isFatal withNSException:(NSException *)exception

Parameters

isFatal

A boolean indicating whether the exception is fatal.

exception

The NSException exception object.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackSocial:withAction:withTarget:

Track social action.

- (BOOL)trackSocial:(NSString *)network withAction:(NSString *)action withTarget:(NSString *)target

Parameters

network

A string representing social network. Must not be nil.

action

A string representing a social action. Must not be nil.

target

A string representing the target. May be nil.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackTimingWithCategory:withValue:withName:withLabel:

Track user timing.

- (BOOL)trackTimingWithCategory:(NSString *)category withValue:(NSTimeInterval)time withName:(NSString *)name withLabel:(NSString *)label

Parameters

category

A string representing a timing category.

time

A timing value.

name

A string representing a timing name, or nil if none.

label

A string representing a timing variable label, or nil if none.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackTransaction:

Track a transaction.

- (BOOL)trackTransaction:(GAITransaction *)transaction

Parameters

transaction

The GAITransaction object.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackView

Track that the current screen (as set in appScreen) was displayed. If appScreen has not been set, this will not generate any tracking information.

- (BOOL)trackView

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed or appScreen is not set).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h

trackView:

Track that the specified view or screen was displayed. This call sets the appScreen property and generates tracking information to be sent to Google Analytics.

- (BOOL)trackView:(NSString *)screen

Parameters

screen

The name of the screen. Must not be nil.

Return Value

YES if the tracking information was queued for dispatch, or NO if there was an error (e.g. the tracker was closed).

Discussion

If [GAI optOut] is true, this will not generate any tracking information.

Declared In

GAITracker.h