Support Center

Integrating the iOS SDK

Last Updated: Feb 07, 2014 12:00PM PST

1. Download the SDK

Log in and download the SDK from the Get the SDK page under Developer Tools.

Please note we offer two iOS SDKs. Our standard iOS SDK includes references to Apple's AdSupport Framework and should be used for applications serving ads.

Due to restrictions enforced by Apple, please use our iOS SDK without AdSupport if your application does not serve ads.

2. Remove old Apsalar SDKs

  1. If the files were placed in the project directory, move them to trash. Otherwise remove the references. 
  2. To confirm that previous versions will not be linked, check the target library search paths and remove any paths to the previous version  

3. Install the SDK

  1. Click on Your App Name > Add Files To 
  2. Select “Create groups for any added folders” and click Add
  3. The following files should now be in your project: libApsalar.a, Apsalar.h, and Apsalar.js
  4. Remove Apsalar.js from Compile Sources
  5. Click on Targets > Your App Name > "Build Phases" tab and then expand ‘Link Binary With Libraries'
  6. Click the “+” to add a library
  7. Add the following libraries:
    • libsqlite3.0.dylib
    • SystemConfiguration.framework
    • Security.framework
    • libz.dylib
    If using our iOS SDK without AdSupport, please skip ahead to Step 4. Please note Apple has added restrictions regarding the AdSupport framework. If your application does not serve adds, do not implement the AdSupport framework. Doing so may cause Apple to reject your application.

    If using our standard iOS SDK, please proceed with steps 3.8 and 3.9 below
  8. If you are using Xcode 4.5, also add AdSupport.framework
  9. If you are building for iOS version below 6.0, modify AdSupport.framework to be linked optionally

4. Integrate the SDK

a) Start an Apsalar session

  1. Import Apsalar class library by adding the following to your AppDelegate file:
    		#import "Apsalar.h"
  2. Add the following to the application:openURL:sourceApplication:annotation and applicationDidBecomeActive functions:
    - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation 
     [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret" andURL:url]; 
     return YES;
    - (void)applicationDidBecomeActive:(UIApplication *)application 
     [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret"];
    using your assigned API Key and secret. These can be found on Developer Tools > Get the SDK.

b) Start tracking events

  1. To track age and gender, use the following methods 
             [Apsalar setAge:(id) age];
    where age is a number between 0 and 100

             [Apsalar setGender: (NSString *) gender];
    where gender is one of two values "f" and "m"
  2. Decide what events you want to track in your application. ApScience does not have any predefined event names, so you can create and use whatever name you like. You can also use the same event name in many places throughout your application, in the case where you actually track that event in more than one place. To help you with deciding which events and attributes to track, we have compiled a set of best practices.
  3. Place calls to one the following three methods into your app for each place you want to track an event. This will register and record all event occurrences. Read about restrictions on event name and event attribute name and value.

    For an event without any arguments

    		+ (void)event:(NSString *)name

    where name is the name you have chosen for the event.

    An example of this call is:  

    		[Apsalar event:@"purchase"];

    For an event with arguments

    		+ (void)eventWithArgs:(NSString *)name, ... 

    where name is the name you have chosen for the event. You may provide one or more argument name/value pairs where an argument name is of type NSString and the value is of type NSDictionaryNSArrayNSNumberNSString or NSNull

    If you are using a variable argument list, eventWithArgs should be nil-terminated:

    		[Apsalar eventWithArgs:@"purchase",
       @"sku", @"12345",
       @"quantity", [NSNumber numberWithInt:2],
       @"price", [NSNumber numberWithDouble:123.45], nil];

    For an event with arguments (NSDictionary)

    		+ (void) event:(NSString *)name withArgs:(NSDictionary *)args;

    where name is the name of the event. The dictionaries passed must contain keys of type NSString with the values being any combination of or nesting of type NSDictionaryNSArrayNSNumberNSString and NSNull.

    The following is an example of how to use event:withArgs: for tracking an add to shopping cart event

    		// Build each shopping cart item
    NSDictionary *item1 = [NSDictionary dictionaryWithObjectsAndKeys:
       @"UPC-018627610014", @"sku",
       [NSNumber numberWithInt:2], @"qty",
       [NSNumber numberWithDouble:8.99], @"unit_price",
       @"USD", @"currency", nil];
    NSDictionary *item2 = [NSDictionary dictionaryWithObjectsAndKeys:
       @"UPC-070271003758", @"sku",
       [NSNumber numberWithInt:1], @"qty",
       [NSNumber numberWithDouble:15.99], @"unit_price",
       @"USD", @"currency", nil];
    NSDictionary *item3 = [NSDictionary dictionaryWithObjectsAndKeys:
       @"ISBN13-978-0-596-51774-8", @"sku",
       [NSNumber numberWithInt:1], @"qty",
       [NSNumber numberWithDouble:29.99], @"unit_price",
       @"USD", @"currency", nil];
    // combine the items into an array -- you could also not combine
    // them and just add each item separately into the
    //  cart as an argument...your choice
    NSArray *contents = [NSArray arrayWithObjects:item1, item2, item3, nil];
    // place the array of items into the top level shopping cart -- the
    // total is hard coded here, but you would normally have calculated this.
    NSDictionary *args = [NSDictionary dictionaryWithObjectsAndKeys:contents,
       [NSNumber numberWithDouble:63.96], @"total",
       @"USD", @"currency",
       @"A556740089", @"member_id", nil];
    // record the event with Apsalar
       [Apsalar event:@"cart" withArgs:args];

c) Advanced settings

  1. The SDK by default sends all events in real-time. To set up and control batching of events, refer to this article.

5. Compile and Run

Compile and run your application to automatically register your application and events. User data should start populating on your dashboard within a few hours.

Note: Event attributes will populate with some delay, after Apsalar batch reports are run.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found