Inherits from NSObject
Declared in LUAPIClient.h
LUAPIClient.m

Overview

LUAPIClient is used to perform requests to the LevelUp API.

Setup

Before using LUAPIClient, it must be set up with a valid API key. This is done with setupWithAppID:APIKey:.

Issuing Requests

The method performRequest:success:failure: is used to issue requests to the LevelUp’s REST API. It performs these requests in the background, and then handles the responses. If the request is successful, the success block is called, passing in the result of the API call. If an error occurs, the failure block is called with an appropriate NSError.

A API request is an instance of LUAPIRequest which has been generated using a request builder class. See the documentation for the request builder for information on specific API calls.

Authentication

When a user logs in, an access token is provided along with the user’s ID. LUAPIClient needs to be given these values so that they can be included in API calls which require an authenticated user. Once stored, these values will be securely stored so that they will persist between application launches.

Development Mode

You can configure the SDK to run in “Development Mode” by configuring the SDK using setupWithAppID:APIKey:developmentMode: or by setting developmentMode to YES. When in Development Mode, all API requests will go to the LevelUp Sandbox server rather than the production API server. The Sandbox server allows you to test the API without charging any money. When in Development Mode, make sure your App ID and API Key are associated with a Sandbox App, configured at https://www.thelevelup.com/developer/sandbox/apps.

Errors

When an API call fails, the failure block passed to performRequest:success:failure: will be called with an NSError object containing additional information about the error. This error will have the domain LUAPIErrorDomain.

Codes

See LUAPIErrorCode in LUConstants.h for a list of possible error codes.

User Info

The userInfo dictionary for this NSError 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.

Example

LUAPIRequest *request = [LUUserRequestFactory requestForCurrentUser];
[[LUAPIClient sharedClient] performRequest:request
                                   success:^(LUUser *user) {
                                     NSLog(@"The current user is %@", user);
                                   }
                                   failure:^(NSError *error) {
                                     NSLog(@"Got an error: %@", error);
                                   }];

Properties

accessToken

The access token of an authenticated user.

@property (copy) NSString *accessToken

Discussion

The access token of an authenticated user.

Declared In

LUAPIClient.h

currentUserID

The user ID of the authenticated user. (Deprecated: This attribute has been deprecated. User IDs are no longer required for any requests.)

@property (copy) NSNumber *currentUserID

Discussion

The user ID of the authenticated user.

Declared In

LUAPIClient.h

deepLinkAuthBundleID

The bundle ID of the app to use for Deep Link Auth. Defaults to LevelUp’s bundle ID.

@property (copy) NSString *deepLinkAuthBundleID

Discussion

The bundle ID of the app to use for Deep Link Auth. Defaults to LevelUp’s bundle ID.

Declared In

LUAPIClient.h

deepLinkAuthInstallAppStoreURL

The URL of the App Store link used to direct the user to the App Store if LevelUp isn’t installed. This URL can be generated at https://linkmaker.itunes.apple.com.

@property (copy) NSURL *deepLinkAuthInstallAppStoreURL

Discussion

The URL of the App Store link used to direct the user to the App Store if LevelUp isn’t installed. This URL can be generated at https://linkmaker.itunes.apple.com.

The default value of this property is the URL to LevelUp on the App Store.

Declared In

LUAPIClient.h

deepLinkAuthInstallMessage

Used to override the default message of the alert shown when a user doesn’t have LevelUp installed.

@property (copy) NSString *deepLinkAuthInstallMessage

Discussion

Used to override the default message of the alert shown when a user doesn’t have LevelUp installed.

Declared In

LUAPIClient.h

deepLinkAuthInstallNegativeButtonTitle

Used to override the title of the negative button of the alert shown when a user doesn’t have LevelUp installed. Tapping this button dismisses the alert.

@property (copy) NSString *deepLinkAuthInstallNegativeButtonTitle

Discussion

Used to override the title of the negative button of the alert shown when a user doesn’t have LevelUp installed. Tapping this button dismisses the alert.

Declared In

LUAPIClient.h

deepLinkAuthInstallPositiveButtonTitle

Used to override the title of the positive button of the alert shown when a user doesn’t have LevelUp installed. Tapping this button brings the user to the App Store.

@property (copy) NSString *deepLinkAuthInstallPositiveButtonTitle

Discussion

Used to override the title of the positive button of the alert shown when a user doesn’t have LevelUp installed. Tapping this button brings the user to the App Store.

Declared In

LUAPIClient.h

deepLinkAuthInstallTitle

Used to override the title of the alert shown when a user doesn’t have LevelUp installed.

@property (copy) NSString *deepLinkAuthInstallTitle

Discussion

Used to override the title of the alert shown when a user doesn’t have LevelUp installed.

Declared In

LUAPIClient.h

deepLinkAuthShowInstallAlert

When a Deep Link Auth request is made and the user doesn’t have the LevelUp app installed, show an alert that directs the user to the App Store to download it. If set to YES, an alert view will automatically be shown, and an error notification will not be thrown. If set to NO, no alert is shown, and instead an error notification is sent with code LUDeepLinkAuthErrorAppNotInstalled.

@property (assign) BOOL deepLinkAuthShowInstallAlert

Discussion

When a Deep Link Auth request is made and the user doesn’t have the LevelUp app installed, show an alert that directs the user to the App Store to download it. If set to YES, an alert view will automatically be shown, and an error notification will not be thrown. If set to NO, no alert is shown, and instead an error notification is sent with code LUDeepLinkAuthErrorAppNotInstalled.

The default value of this property is YES.

Declared In

LUAPIClient.h

deepLinkAuthURLScheme

The URL scheme of the app to use for Deep Link Auth. Defaults to LevelUp’s URL scheme.

@property (copy) NSString *deepLinkAuthURLScheme

Discussion

The URL scheme of the app to use for Deep Link Auth. Defaults to LevelUp’s URL scheme.

Declared In

LUAPIClient.h

developmentMode

Set to YES to enable Development Mode (default is NO).

@property (assign) BOOL developmentMode

Discussion

Set to YES to enable Development Mode (default is NO).

Declared In

LUAPIClient.h

Class Methods

setupWithAppID:APIKey:

Sets up the LevelUp SDK.

+ (void)setupWithAppID:(NSString *)appID APIKey:(NSString *)apiKey

Parameters

appID

Your LevelUp App ID.

apiKey

Your LevelUp API key.

Discussion

Sets up the LevelUp SDK.

This method must be called before performing any API requests.

Declared In

LUAPIClient.h

setupWithAppID:APIKey:developmentMode:

Sets up the LevelUp SDK with the option of turning on development mode.

+ (void)setupWithAppID:(NSString *)appID APIKey:(NSString *)apiKey developmentMode:(BOOL)developmentMode

Parameters

appID

Your LevelUp App ID.

apiKey

Your LevelUp API key.

developmentMode

Specifies if requests should go to the sandbox or production server.

Discussion

Sets up the LevelUp SDK with the option of turning on development mode.

Declared In

LUAPIClient.h

sharedClient

Returns the LUAPIClient singleton used to issue API requests.

+ (LUAPIClient *)sharedClient

Return Value

The shared LUAPIClient instance.

Discussion

Returns the LUAPIClient singleton used to issue API requests.

Exceptions

NSInternalInconsistencyException

If this method is called before setupWithAppID:APIKey:.

Declared In

LUAPIClient.h

Instance Methods

isNetworkReachableOnCellularData

Checks if the network is reachable on cellular data.

- (BOOL)isNetworkReachableOnCellularData

Return Value

YES if the network is reachable and on cellular data, else NO.

Discussion

Checks if the network is reachable on cellular data.

Declared In

LUAPIClient.h

isNetworkReachableOnWifi

Checks if the network is reachable on WiFi.

- (BOOL)isNetworkReachableOnWifi

Return Value

YES if the network is reachable and on WiFi, else NO.

Discussion

Checks if the network is reachable on WiFi.

Declared In

LUAPIClient.h

isNetworkUnreachable

Checks if the network is unreachable.

- (BOOL)isNetworkUnreachable

Return Value

YES if the network is unreachable, else NO.

Discussion

Checks if the network is unreachable.

Declared In

LUAPIClient.h

performRequest:success:failure:

Initiates a LevelUp API request.

- (LUAPIConnection *)performRequest:(LUAPIRequest *)apiRequest success:(LUAPISuccessBlock)success failure:(LUAPIFailureBlock)failure

Parameters

apiRequest

The API request to perform. Request builders can be used to generate these objects.

success

A block to be called upon successful completion of the API request. This block takes a single argument, which is the result of the API call. The type of the object depends on the specific API request.

failure

A block to be called if the API call fails. This block takes a single argument, which is an NSError containing additional information about the error.

Return Value

An LUAPIConnection for the request.

Discussion

Initiates a LevelUp API request.

Declared In

LUAPIClient.h

userAgent

Returns the User-Agent string containing the app name and version, device name and version and LevelUpSDK version.

- (NSString *)userAgent

Return Value

An NSString containing the User-Agent data.

Discussion

Returns the User-Agent string containing the app name and version, device name and version and LevelUpSDK version.

Declared In

LUAPIClient.h