/*! @header GAI.h @abstract Google Analytics iOS SDK Header @version 3.13 @copyright Copyright 2015 Google Inc. All rights reserved. */ #import #import "GAILogger.h" #import "GAITrackedViewController.h" #import "GAITracker.h" typedef NS_ENUM(NSUInteger, GAIDispatchResult) { kGAIDispatchNoData, kGAIDispatchGood, kGAIDispatchError }; /*! Google Analytics product string. */ extern NSString *const kGAIProduct; /*! Google Analytics version string. */ extern NSString *const kGAIVersion; /*! NSError objects returned by the Google Analytics SDK may have this error domain to indicate that the error originated in the Google Analytics SDK. */ extern NSString *const kGAIErrorDomain; /*! Google Analytics error codes. */ typedef enum { // This error code indicates that there was no error. Never used. kGAINoError = 0, // This error code indicates that there was a database-related error. kGAIDatabaseError, // This error code indicates that there was a network-related error. kGAINetworkError, } GAIErrorCode; /*! Google Analytics iOS top-level class. Provides facilities to create trackers and set behaviorial flags. */ @interface GAI : NSObject /*! For convenience, this class exposes a default tracker instance. This is initialized to `nil` and will be set to the first tracker that is instantiated in trackerWithTrackingId:. It may be overridden as desired. The GAITrackedViewController class will, by default, use this tracker instance. */ @property(nonatomic, assign) id defaultTracker; /*! The GAILogger to use. */ @property(nonatomic, retain) id logger; /*! When this is true, no tracking information will be gathered; tracking calls will effectively become no-ops. When set to true, all tracking information that has not yet been submitted. The value of this flag will be persisted automatically by the SDK. Developers can optionally use this flag to implement an opt-out setting in the app to allows users to opt out of Google Analytics tracking. This is set to `NO` the first time the Google Analytics SDK is used on a device, and is persisted thereafter. */ @property(nonatomic, assign) BOOL optOut; /*! If this value is positive, tracking information will be automatically dispatched every dispatchInterval seconds. Otherwise, tracking information must be sent manually by calling dispatch. By default, this is set to `120`, which indicates tracking information should be dispatched automatically every 120 seconds. */ @property(nonatomic, assign) NSTimeInterval dispatchInterval; /*! When set to true, the SDK will record the currently registered uncaught exception handler, and then register an uncaught exception handler which tracks the exceptions that occurred using defaultTracker. If defaultTracker is not `nil`, this function will track the exception on the tracker and attempt to dispatch any outstanding tracking information for 5 seconds. It will then call the previously registered exception handler, if any. When set back to false, the previously registered uncaught exception handler will be restored. */ @property(nonatomic, assign) BOOL trackUncaughtExceptions; /*! When this is 'YES', no tracking information will be sent. Defaults to 'NO'. */ @property(nonatomic, assign) BOOL dryRun; /*! Get the shared instance of the Google Analytics for iOS class. */ + (GAI *)sharedInstance; /*! Creates or retrieves a GAITracker implementation with the specified name and tracking ID. If the tracker for the specified name does not already exist, then it will be created and returned; otherwise, the existing tracker will be returned. If the existing tracker for the respective name has a different tracking ID, that tracking ID is not changed by this method. If defaultTracker is not set, it will be set to the tracker instance returned here. @param name The name of this tracker. Must not be `nil` or empty. @param trackingID The tracking ID to use for this tracker. It should be of the form `UA-xxxxx-y`. @return A GAITracker associated with the specified name. The tracker can be used to send tracking data to Google Analytics. The first time this method is called with a particular name, the tracker for that name will be returned, and subsequent calls with the same name will return the same instance. It is not necessary to retain the tracker because the tracker will be retained internally by the library. If an error occurs or the name is not valid, this method will return `nil`. */ - (id)trackerWithName:(NSString *)name trackingId:(NSString *)trackingId; /*! Creates or retrieves a GAITracker implementation with name equal to the specified tracking ID. If the tracker for the respective name does not already exist, it is created, has it's tracking ID set to |trackingId|, and is returned; otherwise, the existing tracker is returned. If the existing tracker for the respective name has a different tracking ID, that tracking ID is not changed by this method. If defaultTracker is not set, it is set to the tracker instance returned here. @param trackingID The tracking ID to use for this tracker. It should be of the form `UA-xxxxx-y`. The name of the tracker will be the same as trackingID. @return A GAITracker associated with the specified trackingID. The tracker can be used to send tracking data to Google Analytics. The first time this method is called with a particular trackingID, the tracker for the respective name will be returned, and subsequent calls with the same trackingID will return the same instance. It is not necessary to retain the tracker because the tracker will be retained internally by the library. If an error occurs or the trackingId is not valid, this method will return `nil`. */ - (id)trackerWithTrackingId:(NSString *)trackingId; /*! Remove a tracker from the trackers dictionary. If it is the default tracker, clears the default tracker as well. @param name The name of the tracker. */ - (void)removeTrackerByName:(NSString *)name; /*! Dispatches any pending tracking information. Note that this does not have any effect on dispatchInterval, and can be used in conjunction with periodic dispatch. */ - (void)dispatch; /*! Dispatches the next tracking beacon in the queue, calling completionHandler when the tracking beacon has either been sent (returning kGAIDispatchGood) or an error has resulted (returning kGAIDispatchError). If there is no network connection or there is no data to send, kGAIDispatchNoData is returned. Note that calling this method with a non-nil completionHandler disables periodic dispatch. Periodic dispatch can be reenabled by setting the dispatchInterval to a positive number when the app resumes from the background. Calling this method with a nil completionHandler is the same as calling the dispatch above. This method can be used for background data fetching in iOS 7.0 or later. It would be wise to call this when the application is exiting to initiate the submission of any unsubmitted tracking information. @param completionHandler The block to run after a single dispatch request. The GAIDispatchResult param indicates whether the dispatch succeeded, had an error, or had no hits to dispatch. */ - (void)dispatchWithCompletionHandler:(void (^)(GAIDispatchResult result))completionHandler; @end