Tracking in iOS applications

Provided with WT1 is an iOS library aimed at facilitating tracking from iPhone and iPad applications.

• Benefits
• Requirements
• Concept
• Quick start
• API

Benefits

Behind the scene, the WT1 iOS library uses the JSON API using HTTP connections.

The library provides additional features compared to a simple HTTP client:

• To minimize network overhead and battery usage, the tracked events are batched and sent at regular intervals instead of synchronously when the event is tracked.
• To account for network losses and instability, if events cannot be reported, they are automatically saved and retried, even across application restarts.
• Similarly, if the user backgrounds or stops the application before events are sent, they are saved and will be retried the next time the application is put in the foreground

Requirements

The library requires iOS 5 or higher and requires an ARC-enabled project

In order to minimize memory overheads, the tracker does not create additional threads but uses the run loop of the current thread. Therefore:

• All interaction with the tracker must be done in the same thread
• The thread on which interaction with the tracker is done must have a run loop (this is the case of the main thread on an iOS application)

Concepts

In the iOS library:

• The visitoris:
  • When running on iOS 5, the UUID of the iOS device itself
  • When running on iOS 6, the identifierForVendor for your iOS vendor
• The session corresponds to an active time on the application (ie, when the application is put in the background, it terminates the current session).

Quick start

First, include the WT1Tracker.h and WT1Tracker.m files in your iOS application.

To use the tracker, create a tracker object, targeting your API URL (Your web application URL followed by /events. You can then use the trackPage and trackEvent methods.

WT1Tracker* tracker = [WT1Tracker trackerWithUrl:@"http://mytrackerurl.com/events"];
[tracker trackPage:@"mypage"];

API

The tracker is fully implemented in the WT1Tracker class.

/**
 * An events tracker
 */
@interface WT1Tracker : NSObject
 
/** Factory method: create a tracker targeting the given API URL */
+ (WT1Tracker*)trackerWithURL:(NSString*)url;
 
/** Sets the dictionary of session parameters */
- (void)updateSessionParams:(NSDictionary*)dictionary;
/** Sets the dictionary of visitor parameters */
- (void)updateVisitorParams:(NSDictionary*)dictionary;
 
/** Tracks a page view */
- (void)trackPage:(NSString*)page;
/** Tracks a page view, with additional params */
- (void)trackPage:(NSString*)page withParams:(NSDictionary*)params;
/** 
 * Tracks a custom event on a page, with additional params
 * @param page : optional, can be nil
 */
- (void)trackEvent:(NSString*)page withParams:(NSDictionary*)params;
 
/** Force immediate send of queued tracking events */
- (void)sendNow;
 
/** Call this when the application enters background */
- (void)enterBackground;
/** Call this when the application resumes from background */
- (void)enterForeground;
 
/** Target tracker API URL */
@property NSString* trackerURL;
/** Interval in seconds between sends of the queued tracking events. Default is 20 seconds */
@property int sendInterval;
 
@end

For more information on custom variables, see Custom variables in iOS