Getting Started: Android

Mobile SDK / Getting Started

NOTE: If you do not have SDK repo access, all SDK links on this page will route to a 404. Request access to the SDK to view the private repos.

Overview

The Android LevelUp SDK provides the basic building blocks you’ll need to integrate LevelUp into your app. Specifically, this provides classes which allow you to make requests to the LevelUp web service and handle the results. As there are many UI styles and preferences in the Android community the SDK doesn’t mandate using anything in particular.

While the SDK itself doesn’t contain UI components, we don’t want to leave you completely in the cold. The sample app provides a bare-bones implementation of a UI built on top of the LevelUp SDK.

Requirements

The LevelUp SDK is designed to work with the Android Gradle build system. Currently, only Android Studio and Gradle builds are supported; Eclipse and Ant are no longer supported.

The LevelUp SDK requires a number of libraries, most of which are included by way of Gradle.

The LevelUp SDK sample is dependent on the SDK library project. Instructions on setting up the sample are below.

API key

To use the LevelUp SDK, you will need to first get a LevelUp API key.

Installation

To get a good feel for how to use the SDK, first download the SDK sample app. This will walk you through the basics of doing deep link auth and showing a payment token. For Enterprise developers, this also demonstrates logging in and registering users.

It is recommended to get the latest SDK version by way of Git. If you’re unfamiliar with Git, please see the GitHub Getting Started Guide.

Getting the SDK

The sample app contains everything you need to get up and running. The SDK itself is included by way of a git submodule. You can have git automatically download and checkout the submodule by using the --recursive option as shown below:

git clone --recursive git@github.com:TheLevelUp/levelup-sdk-sample-android.git

If you want to get just the SDK (without the sample), just do:

git clone git@github.com:TheLevelUp/levelup-sdk-android.git

Set the API key

Before any requests can be made, you need to set the API key via resource overlays. For those unfamiliar with resource overlays, this is just a way of overriding an SDK-provided resource (the stuff in res/) with your own.

In this case, the API key must be put in the levelup_api_key string resource. An example of this is in the sample in doc/strings_api_keys.xml which should be copied to the sample’s res/values/ directory. This will be read by the AccessTokenRequestFactory when you build a request.

cp doc/strings_api_keys.xml levelup-sdk-sample/res/values/

Then edit the strings file to add in the API key:

$EDITOR levelup-sdk-sample/res/values/strings_api_keys.xml

In addition to the API key, for deep link auth to work, you must set your app’s LevelUp App ID by setting the levelup_app_id string resource overlay. This App ID should have been provided to you when you got your API key.

Building the Sample with Android Studio

Open Android Studio and go to File → Open…. Then select sample app’s project in levelup-sdk-sample-android.

Once built, run the levelup-sdk-sample app.

Building the Sample with Gradle

To compile the sample, do the usual:

./gradlew assembleDebug

Performing Requests

The LevelUp web service API is a RESTful HTTP API. The SDK provides a number of classes which can be used in concert to perform requests. As there are a number of ways to manage background threads in Android, the task of executing requests in the background is left up to the reader. The sample provides a demonstration of using a Loader for this purpose.

Sending Requests

Requests are made by using request factories to generate an AbstractRequest. These requests are then sent to the web service using a LevelUpConnection which will return an instance of an LevelUpResponse.

At this stage, the LevelUpResponse should be checked for an LevelUpStatus.OK status code. If the request was successful, model JSON factories can turn this response into a simple POJO model. If there was an error performing the request, there are a few things that need to be checked.

Handling Errors

When the response Content-Type header is set to application/json, the error messages can be retrieved by calling LevelUpResponse.getServerErrors(). This is usually returned on form validation errors and includes information about which form field needs to be corrected.

Other status codes indicate various types of server/client errors and should be displayed to the user appropriately.

If the status is LevelUpStatus.LOGIN_REQUIRED, either the request needs to be made with authorization or the user is no longer logged in (their access token has expired or been invalidated).

Authorization

Most requests need to be authorized with an AccessToken. Non-enterprise apps must use deep link authorization to obtain an AccessToken for the user. This token should be persisted until the server requests that it be revoked. Generally, this means that the AccessToken should be stored in a private SQLiteDatabase or using SharedPreferences. See the sample code for an example of persisting this using SharedPreferences.

When implementing your own AccessToken storage mechanism, you must implement the AccessTokenRetriever and Parcelable interfaces.