The iOS LevelUp SDK
Objective-C Ruby
Failed to load latest commit information.
External Add Framework target with namespaced dependencies Apr 29, 2014
Integration-Tests/Tests LU-11931 Change id to instancetype for initializers Aug 16, 2016
LevelUpSDK.xcodeproj [Enhancement] LU-13189 Create script to automate SDK version bumps Dec 18, 2016
LevelUpSDK.xcworkspace Moved LevelUpSDKTests to "Unit Tests" to match apps Mar 29, 2013
Source Version bump: 1.13.1 Dec 8, 2016
Testing LU-13122 Add request for locations including per_page parameter Dec 8, 2016
Unit-Tests LU-13122 Add request for locations including per_page parameter Dec 8, 2016
.gitattributes Version bump: 0.22.2 Jan 27, 2014
.gitignore LU-10248 Ensure xcodebuild error codes are treated as test failures Oct 2, 2015
.travis.yml LU-13043 Update LevelUpSDK to support CircleCI Dec 1, 2016
Gemfile [Enhancement] LU-13189 Create script to automate SDK version bumps Dec 18, 2016
Gemfile.lock [Enhancement] LU-13189 Create script to automate SDK version bumps Dec 18, 2016
LICENSE Set Apache 2.0 as the license Jul 16, 2014
LevelUpSDK.podspec Version bump: 1.13.2 Dec 13, 2016
Podfile LU-13038 Fix OHHTTPStubs Private API usage issue Nov 30, 2016
Podfile.lock LU-13038 Fix OHHTTPStubs Private API usage issue Nov 30, 2016 LU-9540 Update May 18, 2015
Rakefile Refresh database seed May 6, 2015
ci.rb LU-13043 Update LevelUpSDK to support CircleCI Dec 1, 2016
circle.yml LU-13071 Limit Circle builds Dec 2, 2016
version_bump.rb [Enhancement] LU-13189 Create script to automate SDK version bumps Dec 18, 2016

The LevelUp SDK allows developers to build apps that integrate with the LevelUp platform.


The primary purpose of the SDK is to make it easy to issue requests to the LevelUp platform. It provides a layer on top of LevelUp's REST API. Requests may be things like signing up, logging or viewing nearby merchants. In addition, the SDK contains several utility classes to help with scanning and generating QR codes. Read below for additional information, or check out the complete documentation for a look at all the classes available with the SDK.

The recommended way to access the LevelUp SDK is through CocoaPods.

Interacting with the API

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 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) {
                                     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 a result. This result differs for each call; for example, a request for the current user returns an LUUser, while a request for nearby merchants would return an NSArray of LUMerchant objects. The documentation for each request factory specifies the object which will be passed to success.

If the API request fails, an NSError instance will be passed to the failure block. The userInfo dictionary for this NSError has keys with several additional pieces of information:

  • LUAPIFailingURLRequestErrorKey: An NSURLRequest containing the request.
  • LUAPIFailingURLResponseErrorKey: An NSURLResponse containing the response.
  • LUAPIFailingErrorMessageErrorKey: An optional error message from the server.
  • LUAPIFailingJSONResponseErrorKey: An optional JSON response from the server.

Generating and Scanning Codes

A core feature of an app built on the LevelUp platform is the ability to display QR codes (so that users can pay) and to scan QR codes (so that users can claim campaigns). The SDK provides two classes to assist with these actions.

Generating Codes

The LUPaymentQRCodeGenerator class is used to generate a UIImage containing user's QR code, along with optional information such as a tip percentage.

To generate a QR code for an arbitrary NSString, use LUGenericQRCodeGenerator.

Scanning Codes

LUQRCodeScannerView is a UIView that handles scanning QR codes. It is provided with a delegate to be notified when a scan is successful.


The SDK contains several optional classes to assist in testing. These can be included through a CocoaPods subspec called "Testing". The header file for these classes is LevelUpSDKTesting.h.

There are two main categories of testing classes: factories and network stubs.


To aid in testing, fake test instances of all the main LevelUp SDK classes are available. These are added in categories to the classes. For example, getting a test user is as simple as calling [LUUser fakeInstance]. For a full list of fake instances, see the header files in Testing/Factories.

Network Stubs

Network stubs are also provided for all common requests. These allow you to stub out network calls so that canned responses are returned instead of connecting to the server. This is done transparently to your code.

Use the LUAPIStubbing class to manage stubs. The addStub: method adds a stub, and clearStubs clears all stubs. Two optional methods are also available: disableNetConnect and raiseOnUnexpectedRequest:. The disableNetConnect method will block all network requests and return an error for any request that does not match a stub. The related raiseOnUnexpectedRequest: method will cause an exception to also be raised when this happens. This can be useful for finding places where stubs need to be added.

Stubs are instances of the LUAPIStub class. LUAPIStubFactory provides methods to create stubs for many of the common use cases of the API. See LUAPIStubFactory.h in Testing/Network-Responses for a full list of methods.

Here's a simple example of how to use network stubs:

[[LUAPIStubbing sharedInstance] disableNetConnect];
[[LUAPIStubbing sharedInstance] addStub:[LUAPIStubFactory stubToGetCurrentUser]];

LUAPIRequest *request = [LUUserRequestFactory requestForCurrentUser];
[[LUAPIClient sharedClient] performRequest:request
                                   success:^(LUUser *user) {
                                     // ...
                                   failure:^(NSError *error) {
                                     // ...

[[LUAPIStubbing sharedInstance] clearStubs];

Developer Terms

By enabling LevelUp integrations, including through this SDK, you agree to LevelUp's developer terms.

Security Response

LevelUp takes the security of its users and the safety of their information very seriously. See our security and security response pages for more information.


Copyright (C) 2015 SCVNGR, Inc. d/b/a LevelUp

Except as otherwise noted, the LevelUp SDK for iOS is licensed under the Apache License, Version 2.0 (

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.