code.grnet.gr Git - pithos-ios/blob - Classes/GANTracker.h

   1 //
   2 //  GANTracker.h
   3 //  Google Analytics iPhone SDK.
   4 //  Version: 1.1
   5 //
   6 //  Copyright 2009 Google Inc. All rights reserved.
   7 //
   8
   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;
  18
  19 @protocol GANTrackerDelegate;
  20 typedef struct __GANTrackerPrivate GANTrackerPrivate;
  21
  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 {
  25  @private
  26   GANTrackerPrivate *private_;
  27 }
  28
  29 // Singleton instance of this class for convenience.
  30 + (GANTracker *)sharedTracker;
  31
  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
  35 // supplied.
  36 - (void)startTrackerWithAccountID:(NSString *)accountID
  37                    dispatchPeriod:(NSInteger)dispatchPeriod
  38                          delegate:(id<GANTrackerDelegate>)delegate;
  39
  40 // Stop the tracker.
  41 - (void)stopTracker;
  42
  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;
  48
  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;
  58
  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
  62 // a session.
  63 - (BOOL)setCustomVariableAtIndex:(NSUInteger)index
  64                             name:(NSString *)name
  65                            value:(NSString *)value
  66                            scope:(NSUInteger)scope
  67                        withError:(NSError **)error;
  68
  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
  71 // custom variables.
  72 - (BOOL)setCustomVariableAtIndex:(NSUInteger)index
  73                             name:(NSString *)name
  74                            value:(NSString *)value
  75                        withError:(NSError **)error;
  76
  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;
  80
  81 // Manually dispatch pageviews/events to the server. Returns YES if
  82 // a new dispatch starts.
  83 - (BOOL)dispatch;
  84
  85 @end
  86
  87 @protocol GANTrackerDelegate <NSObject>
  88
  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;
  95
  96 @end