GAITracker Protocol Reference
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
property required methodCFBundleName
string from the application bundle. If you wish to override this property, you must do so before making any tracking calls. -
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
property required methodnil
. If you wish to set this property, you must do so before making any tracking calls. -
appVersion
The application version associated with this tracker. By default, this property is populated with the
property required methodCFBundleShortVersionString
string from the application bundle. If you wish to override this property, you must do so before making any tracking calls. -
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
property required methodNO
when the tracker is first obtained. -
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