Getting Started: iOS

Mobile SDK / Getting Started


There are two ways to install the LevelUp SDK: CocoaPods, and a pre-compiled framework.


The recommended way to access the LevelUp SDK is through CocoaPods. If you’ve never used CocoaPods before, install it by running:

$ gem install cocoapods
$ pod setup

To add the SDK as a dependency in your project, edit a text file called Podfile in your Xcode project directory:

platform :ios, '6.0'
pod 'LevelUpSDK'

To install the SDK:

pod install

If your project doesn’t have an Xcode workspace, one will be created. Be sure to open this workspace file and not your project file when working on your app.


You can also install the LevelUp SDK using a precompiled framework. This framework contains the SDK as well as all of its dependencies. All classes and other symbols of the dependencies have been namespaced, which means you can use different versions of the SDK’s dependencies without having any build conflicts.

Installation instructions:

  1. Visit our releases page and download “” from the latest release.
  2. Unzip “”.
  3. Open your project in Xcode, and drag “LevelUpSDK.embeddedframework” into the Project Navigator. Make sure “Create groups for any added folders” is selected, and “Copy items into destination group’s folder” is checked: LevelUp App
  4. Ensure that the following frameworks are added to your project: AVFoundation, CoreData, CoreGraphics, CoreLocation, CoreMedia, CoreVideo, ImageIO, MobileCoreServices, QuartzCore, Security, and SystemConfiguration. You can do this by selecting your project file, selecting your build target, and selecting the “Build Phases” tab. Under “Link Binary With Libraries”, press “+” and add each framework.
  5. Select your project file, then select your build target, then the “Build Settings” tab. Find the Other Linker Flags setting, and make sure that “-ObjC” is one of the flags.
  6. Import the main header file in your code:
#import <LevelUpSDK/LevelUpSDK.h>

Performing Requests

Interactions with the LevelUp API occur through the LUAPIClient class. This is a singleton class through which all requests are performed.

Before issuing any requests, you must register an App ID and API key . This is done using the setupWithAppID:APIKey: method:

[[LUAPIClient sharedClient] setupWithAppID:APP_ID APIKey:API_KEY];

An API request is an instance of LUAPIRequest. The SDK includes a set of request factories in order to create these requests.

Requests are performed by calling performRequest:success:failure::

LUAPIRequest *request = [LUUserRequestFactory requestForCurrentUser];
[[LUAPIClient sharedClient] performRequest:request
                                   success:^(LUUser *user, LUAPIResponse *response) {
                                     NSLog(@"Retrieved user: %@", user);
                                   failure:^(NSError *error) {
                                     NSLog(@"Error while retrieving user: %@");

When the API call is successful, the success block will be called, and will be passed two parameters. The first is the result. This result differs for each call; for example, a request for the current user returns an LUUser, while a request for nearby locations would return an NSArray of LULocation objects. The documentation for each request factory specifies the result which will be returned. The second parameter to the success block is an instance of LUAPIResponse.


For most API calls, you will be want to be authorized as a user. Use Deep Link Auth to request one or more permissions from the user. When the request succeeds, you will be given an access token. Setting the accessToken property of the LUAPIClient singleton object will cause future requests to be authorized using this token:

[LUAPIClient sharedClient].accessToken = accessToken;

Once set, this field will be automatically persisted by the SDK using the secure Keychain.


If an API request fails, an NSError instance will be passed to the failure block. This NSError instance will have the domain LUAPIErrorDomain, and one of several possible codes:

  • LUAPIErrorLoginRequired: The client must be logged in to complete the request.
  • LUAPIErrorMaintenance: The server is currently down for maintenance.
  • LUAPIErrorNetwork: Was unable to get to the server because the network is down.
  • LUAPIErrorParsing: The server responded with JSON that couldn’t be parsed.
  • LUAPIErrorServer: The server responded with an error.
  • LUAPIErrorUpgrade: The SDK needs to be upgraded.

In addition, the userInfo dictionary has keys for several pieces of information:

  • LUAPIErrorKeyAPIErrors: An optional array of LUAPIError objects returned by the server.
  • LUAPIErrorKeyErrorMessage: An optional error message from the server. If multiple errors were returned, this will only contain the first message. LUAPIErrorKeyAPIErrors can be used to see all errors.
  • LUAPIErrorKeyJSONResponse: An optional JSON response from the server.
  • LUAPIErrorKeyOriginalError: If this error was generated from another NSError, it is included under this key.
  • LUAPIErrorKeyURLResponse: An NSURLResponse containing the response.


To see how an app can handle requests, authorization, and errors, check out our sample app for the LevelUp SDK on iOS.