Integrating the iOS SDK

Last Updated: Jun 28, 2016 01:57PM PDT

1. Download the SDK

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

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
    • AdSupport.framework
    • iAd.framework

  8. Important - Apple's iOS 9 release- We have successfully tested our SDK with latest iOS 9 GM candidate.
    i) For the apps built with iOS 8 and previous SDKs: The app will continue to work without needing any changes when run on iOS 9.
    ii) For the apps that are built with iOS 9 SDK:
     Edit your app's Info.plist file to add the Apsalar endpoint as an exception to support Apple's App Transport Security feature in new in iOS 9.  You can read Apple's iOS 9 release notes here, and tech notes on App Transport Security here.  If your app uses any other non-SSL enabled endpoint, they must be added to the Info.plist file as well. 

    Via XML:
    Via UI:
Important: Apple has updated their stance on usage of the IDFA in cases of attribution and advertising optimization and have put the responsibility on developers to ensure they are using the IDFA responsibly. We want to assure you that Apsalar makes every effort to follow the usage guidelines outlined by Apple when handling IDFA information.

If you wish to use the iOS 6.0.8 SDK or later, you must include both the iAd and AdSupport frameworks. 

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. For most apps, add the following to the applicationDidBecomeActive function:
    - (void)applicationDidBecomeActive:(UIApplication *)application 
     [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret"];
    If your app uses Javascript and you want to send Asalar events from inside Javascript, then you may want to start a session from openURL, like this:
    - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation 
     [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret"]; 
     return YES;
    using your assigned API Key and secret. These can be found on Developer Tools > Get the SDK.
  3. If you're using Apsalar iOS SDK 7.1 and above, and are using deeplinks, pass the launch URL into the Apsalar start session call like in the below example.  Note: this is required if you would like to run Google app engagement campaigns which require deeplinking technology
     AppDelegate *delegate = [[UIApplication sharedApplication] delegate]
     [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret" andLaunchURL:delegate.launchURL];

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. While there are a few restrictions on event and attribute names, you can generally use whichever names you prefer. To help you decide 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. In the case where you actually track a single event in more than one place, you can use the same event name throughout your application.

    For revenue events, Apsalar offers automated IAP tracking for iOS applications. Please see our guide for revenue events for more specific information.

    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.

iOS Uninstall SDK Support

Apsalar is proud to announce iOS uninstall as a new feature!  Please reach out to your account manager, or our support team at if you would like more information on enabling this for your iOS app.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found