3 // Google Analytics iPhone SDK.
6 // Copyright 2009 Google Inc. All rights reserved.
9 extern NSString* const kGANTrackerErrorDomain;
10 extern NSInteger const kGANTrackerNotStartedError;
11 extern NSInteger const kGANTrackerInvalidInputError;
12 extern NSInteger const kGANTrackerEventsPerSessionLimitError;
13 extern NSUInteger const kGANMaxCustomVariables;
14 extern NSUInteger const kGANMaxCustomVariableLength;
15 extern NSUInteger const kGANVisitorScope;
16 extern NSUInteger const kGANSessionScope;
17 extern NSUInteger const kGANPageScope;
19 @protocol GANTrackerDelegate;
20 typedef struct __GANTrackerPrivate GANTrackerPrivate;
22 // Google Analytics tracker interface. Tracked pageviews and events are stored
23 // in a persistent store and dispatched in the background to the server.
24 @interface GANTracker : NSObject {
26 GANTrackerPrivate *private_;
29 // Singleton instance of this class for convenience.
30 + (GANTracker *)sharedTracker;
32 // Start the tracker by specifying a Google Analytics account ID and a
33 // dispatch period (in seconds) to dispatch events to the server
34 // (or -1 to dispatch manually). An optional delegate may be
36 - (void)startTrackerWithAccountID:(NSString *)accountID
37 dispatchPeriod:(NSInteger)dispatchPeriod
38 delegate:(id<GANTrackerDelegate>)delegate;
43 // Track a page view. The pageURL must start with a forward
44 // slash '/'. Returns YES on success or NO on error (with outErrorOrNULL
45 // set to the specific error).
46 - (BOOL)trackPageview:(NSString *)pageURL
47 withError:(NSError **)error;
49 // Track an event. The category and action are required. The label and
50 // value are optional (specify nil for no label and -1 or any negative integer
51 // for no value). Returns YES on success or NO on error (with outErrorOrNULL
52 // set to the specific error).
53 - (BOOL)trackEvent:(NSString *)category
54 action:(NSString *)action
55 label:(NSString *)label
56 value:(NSInteger)value
57 withError:(NSError **)error;
59 // Set a custom variable. visitor and session scoped custom variables are stored
60 // for later use. Session and page scoped custom variables are attached to each
61 // event. Visitor scoped custom variables are sent only on the first event for
63 - (BOOL)setCustomVariableAtIndex:(NSUInteger)index
65 value:(NSString *)value
66 scope:(NSUInteger)scope
67 withError:(NSError **)error;
69 // Set a page scoped custom variable. The variable set is returned with the
70 // next event only. It will overwrite any existing visitor or session scoped
72 - (BOOL)setCustomVariableAtIndex:(NSUInteger)index
74 value:(NSString *)value
75 withError:(NSError **)error;
77 // Returns the value of the custom variable at the index requested. Returns
78 // nil if no variable is found or index is out of range.
79 - (NSString *) getVisitorCustomVarAtIndex:(NSUInteger)index;
81 // Manually dispatch pageviews/events to the server. Returns YES if
82 // a new dispatch starts.
87 @protocol GANTrackerDelegate <NSObject>
89 // Invoked when a dispatch completes. Reports the number of events
90 // dispatched and the number of events that failed to dispatch. Failed
91 // events will be retried on next dispatch.
92 - (void)trackerDispatchDidComplete:(GANTracker *)tracker
93 eventsDispatched:(NSUInteger)eventsDispatched
94 eventsFailedDispatch:(NSUInteger)eventsFailedDispatch;