Repository files navigation

ARAnalytics is to iOS whatAnalytical is to ruby, orAnalytics.js is to javascript.

ARAnalytics is an analytics abstraction library offering a sane API for tracking events and user data. It currently supports on iOS: Mixpanel, Localytics, Flurry, GoogleAnalytics, KISSmetrics, Crittercism, Crashlytics, Fabric, Bugsnag, Countly, Helpshift, Tapstream, NewRelic, Amplitude, HockeyApp, HockeyAppLib, ParseAnalytics, HeapAnalytics, Chartbeat, UMengAnalytics, Librato, Segmentio, Swrve, YandexMobileMetrica, Adjust, AppsFlyer, Branch, Snowplow, Sentry, Intercom, Keen, Adobe and MobileAppTracker/Tune. And for OS X: KISSmetrics, Mixpanel and HockeyApp.

It does this by using CocoaPods subspecs to let you decide which libraries you'd like to use. You are free to also use the official API for any provider too. Also, it comes with an amazingDSL to clear up your methods.

Changelog

You shouldn't just use:pod "ARAnalytics". Since CocoaPods 0.36+ you should do something like:

pod"ARAnalytics",:subspecs=>["Mixpanel","Segmentio","HockeyApp"]

Once you'vepod installed'd the libraries you can either use the individual (for example)[ARAnalytics setupTestFlightWithTeamToken:@"TOKEN"] methods to start up each individual analytics platform or use the generic setupWithAnalytics with our constants.

  [ARAnalyticssetupWithAnalytics:@{      ARCrittercismAppID :@"KEY",      ARKISSMetricsAPIKey :@"KEY",      ARGoogleAnalyticsID :@"KEY"   }];

Submit a console log that is stored online, for crash reporting this provides a great way to provide breadcrumbs.ARLog(@"Looked at Artwork (%@)", _artwork.name);

externvoidARLog (NSString *format, ...);

/// Submit user events+ (void)event:(NSString *)event;+ (void)event:(NSString *)event withProperties:(NSDictionary *)properties;// Add extra properties to get sent along with every event+ (void)addEventSuperProperties:(NSDictionary *)superProperties;/// Let ARAnalytics deal with the timing of an event+ (void)startTimingEvent:(NSString *)event;+ (void)finishTimingEvent:(NSString *)event;

/// Submit errors to providers+ (void)error:(NSError *)error;+ (void)error:(NSError *)error withMessage:(NSString *)message;

/// Set a per user property+ (void)identifyUserWithID:(NSString *)userID andEmailAddress:(NSString *)email;+ (void)setUserProperty:(NSString *)property toValue:(NSString *)value;+ (void)incrementUserProperty:(NSString*)counterName byInt:(int)amount;

/// Monitor Navigation changes as page view+ (void)pageView:(NSString *)pageTitle;+ (void)monitorNavigationViewController:(UINavigationController *)controller;

On top of this you get access to use the original SDK. ARAnalytics provides a common API between lots of providers, so it will try to map most of the functionality between providers, but if you're doing complex things, expect to also use your provider's SDK.

There is also a DSL-like setup constructor in theARAnalytics/DSL subspec that lets you do all of your analytics setup at once. Example usage:

[ARAnalyticssetupWithAnalytics: @{/* keys*/ }configuration: @{   ARAnalyticsTrackedScreens: @[ @{      ARAnalyticsClass: UIViewController.class,      ARAnalyticsDetails: @[ @{          ARAnalyticsPageNameKeyPath:@"title",      }]  }],   ARAnalyticsTrackedEvents: @[@{      ARAnalyticsClass: MyViewController.class,      ARAnalyticsDetails: @[ @{          ARAnalyticsEventName:@"button pressed",          ARAnalyticsSelectorName:NSStringFromSelector(@selector(buttonPressed:)),      },      @{          ARAnalyticsEventName:@"switch switched",          ARAnalyticsSelectorName:NSStringFromSelector(@selector(switchSwitched:)),      }]   },   ...

The above configuration specifies that the "button pressed" event be sent whenever the selectorbuttonPressed: is invoked onany instance ofMyViewController. Additionally, every view controller will send a page view with its title as the page name wheneverviewDidAppear: is called. There are also advanced uses using blocks in the DSL to selectively disable certain events, provide custom page/event property dictionaries, or to provide dynamic page/event names.

[ARAnalyticssetupWithAnalytics: @{/* keys*/ }configuration: @{   ARAnalyticsTrackedScreens: @[ @{      ARAnalyticsClass: UIViewController.class,      ARAnalyticsDetails: @[ @{          ARAnalyticsProperties: ^NSDictionary*(MyViewController *controller,NSArray *parameters) {return @{/* Custom screen view properties*/ };          },           ARAnalyticsPageNameBlock:  ^NSDictionary*(MyViewController *controller,NSArray *parameters,NSDictionary *customProperties) {return [NSStringstringWithFormat:@"%@:%@:%@",controller.a, controller.b, controller.c];          }      }]  }],  ARAnalyticsTrackedEvents: @[ @{    ARAnalyticsClass: MyViewController.class,    ARAnalyticsDetails: @[       @{        ARAnalyticsSelectorName:NSStringFromSelector(@selector(buttonPressed:)),        ARAnalyticsShouldFire: ^BOOL(MyViewController *controller,NSArray *parameters) {return/* some condition*/;        },        ARAnalyticsProperties: ^NSDictionary*(MyViewController *controller,NSArray *parameters) {return @{/* Custom properties*/ };        },        ARAnalyticsEventNameBlock:  ^NSDictionary*(MyViewController *controller,NSArray *parameters,NSDictionary *customProperties) {return [NSStringstringWithFormat:@"%@ pressed", [(UIButton*)parameters[0]titleLabel].text];        }      },/* more events for this class*/    ]  },  ...

Note that when using page tracking onUIViewControllers,all instancesmust have a non-nil value for theirtitle property. If your app uses nested view controllers, that may not be the case. In this instance, use theARAnalyticsShouldFire block to disable these view controllers from firing analytics events.

ARAnalyticsShouldFire: ^BOOL(MyViewController *controller,NSArray *parameters) {return controller.title !=nil;},

Starting with HockeyApp version 3.7.0, the HockeyApp provider will automatically keep logs of events and include those in crash reports, thus adding ‘breadcrumbs’ to your report and hopefully providing helpful context for your crash reports. Any messages logged withARLog() will also get included in the report.

Note, however, that on iOSsyslogd will not keep logs around for a long time, as such you should only expect logs of people that re-start the application immediately after the application crashing.

iOS:Mixpanel,Localytics,Flurry,GoogleAnalytics,Firebase,KISSmetrics,Crittercism,Countly,Bugsnag,Helpshift,Tapstream,NewRelic,Amplitude,HockeyApp,HockeyAppLib,ParseAnalytics,HeapAnalytics,Chartbeat,UMengAnalytics,Segmentio,Swrve,YandexMobileMetrica,Adjust,Intercom,Librato,Crashlytics,Fabric,AppsFlyer,Branch,Snowplow,Sentry,Keen,Adobe,MobileAppTracker,Leanplum &Appboy.

OSX:KISSmetricsOSX,HockeyAppOSX,MixpanelOSX &ParseAnalyticsOSX.

SeeContributing