Integrating the iOS SDK

Last Updated: Jul 05, 2016 09:39AM 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:
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>e.apsalar.com</key>
            <dict>
                <key>NSExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
        </dict>
    </dict>
    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,
       @"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 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!
support@apsalar.com
http://assets1.desk.com/
apsalarinc
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
Invalid characters found
/customer/en/portal/articles/autocomplete