1955-add Google Analytics feature

ios/widget/GA/GAI.h

@@ -0,0 +1,192 @@
+/*!
+ @header    GAI.h
+ @abstract  Google Analytics iOS SDK Header
+ @version   3.17
+ @copyright Copyright 2015 Google Inc. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+
+#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<GAITracker> defaultTracker;
+
+/*!
+ The GAILogger to use.
+ */
+@property(nonatomic, retain) id<GAILogger> 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<GAITracker>)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<GAITracker>)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