Integrating the iOS SDK

Last Updated: Nov 17, 2016 03:04PM PST

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. Click on Targets > Your App Name > "Build Phases" tab and then expand ‘Link Binary With Libraries'
  5. Click the “+” to add a library
  6. Add the following libraries:
    • libsqlite3.0.dylib
    • SystemConfiguration.framework
    • Security.framework
    • libz.dylib
    • AdSupport.framework
    • iAd.framework

  7. Important - Apple's iOS Version Support and the Apsalar SDK

    i) For the apps that are built against iOS 9: If you're using an Apsalar non-SSL-enabled iOS 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:

    ii) For the apps that are built against iOS 10+: Apple's App Transport Security feature is now required in iOS 10 and above.  Please ensure you're utilizing the Apsalar SSL-enabled iOS SDK available in our Get SDK page.
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 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 *)app openURL:(NSURL *)url options:(NSDictionary *)options 
     [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, also 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.

    For deeplinks
    - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
      [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret" andLaunchURL:url];
      return YES;
    For Universal Links
    - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler{
       if ([userActivity.activityType isEqualToString: NSUserActivityTypeBrowsingWeb]) {
            NSURL *url = userActivity.webpageURL;
           [Apsalar startSession:@"yourAPIKey" withKey:@"yourSecret" andLaunchURL:url];
       return YES;

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

With the Apsalar iOS SDK version 7.2 and above, Apsalar can track your iOS app's uninstalls. If you app currently doesn't support push notifications, you can follow our quick guide here, or Apple's guide here.   If you're app already supports Apple push notifications, all you need to do is pass the device token returned from APNS using the below Apsalar method:
+ (void)registerDeviceTokenForUninstall:(NSData *)deviceToken;
Device tokens resemble a value like b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052. If you are already retrieving a device token from an existing push notification implementation, you can use that value into registerDeviceTokenForUninstall.

Once the above steps are implemented in your app and your APNS certificate is provided to Apsalar as per our instructions here, you're all set to track your iOS apps' uninstalls with Apsalar!
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found