Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The iOS LevelUp SDK
Objective-C Other

Version bump: 1.8.1

* Use correct base URL for OAuth2 requests
latest commit a161b1657f
@cwalcott cwalcott authored
Failed to load latest commit information.
Integration-Tests/Tests Fix Travis builds
LevelUpSDK.xcodeproj Version bump: 1.8.1
LevelUpSDK.xcworkspace Moved LevelUpSDKTests to "Unit Tests" to match apps
Source Version bump: 1.8.1
Testing Add merchantID to LUAccessToken
.gitattributes Version bump: 0.22.2
.gitignore Update .gitignore
Gemfile Set up Unit Testing w/ Travis CI
Gemfile.lock Set up Unit Testing w/ Travis CI
LICENSE Set Apache 2.0 as the license
Podfile Add support for LevelUp iBeacon monitoring
Podfile.lock Move client-side encryption code directly into SDK Add "Security Response" section to the README
travis.rb Fix Travis builds

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 (see "Request Factories" below).

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.


The SDK includes model classes for LevelUp domain objects, such as a user or a merchant. Instances of these objects may be returned from API calls, or may be referenced from other model objects.

  • LUAccessToken: An access token is created when a user successfully logs in, and is used to maintain an authentication session.
  • LUCampaign: Campaigns are promotions which can be claimed by users.
  • LUCategory: A merchant category, such as "Italian" or "Bar".
  • LUClaim: Represents a user's claim on a campaign.
  • LUCohort: When a user claims a campaign, they do so through a cohort. This could be through a social network or a particular advertisement.
  • LUCreditCard: Users have one or more credit cards to use as payment methods.
  • LUInterstitial: Interstitial actions may be shown on some merchant or receipt screens to promote a campaign.
  • LULocation: A merchant has one or more locations, which are physical places users can pay.
  • LULoyalty: Contains information about a user's loyalty progress at a specific merchant.
  • LUMonetaryValue: Represents an amount of money of a specific currency.
  • LUOrder: An order that has been placed using LevelUp.
  • LUPaymentToken: The user's payment token.
  • LUUser: Represents a user of LevelUp.

Request Factories

The SDK includes a set of request factories, which generate a particular LUAPIRequest. Some may require additional input, such as a merchant ID, which must be provided in order to retrieve a given merchant.

Below is the full list of request factories:

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) 2014 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.

Something went wrong with that request. Please try again.