Getting Started

If you are starting with a fresh Android project or an existing app, follow these steps to add the Kinvey Android library to your app and set up the Kinvey Client.


  • Java Development Kit (JDK) 1.6
  • Android SDK simply follow the installation instructions. This library currently supports Android 2.3 and higher.
  • An IDE, such as Eclipse or Android Studio, with ADT installed.

Manual Project Set Up


  1. In Eclipse, create a new Android project: File → New → Project → Android Project. Name it appropriately (eg, "yourapp-android"). Choose Android build target. Specify a package name (eg, "com.yourapp"). Next to "Create Activity" enter "YourAppActivity". Click Finish.
  2. Download the latest Kinvey library (zip) and extract the downloaded zip file.
    • copy all jars in the libs folder of the extracted zip to your project's libs folder on the file system, create the libs folder if it doesn't exist.
  3. Right click on your project → Build Path → Configure Build Path and on the Order and Export tab ensure Android Private Libraries is checked.
  4. In Eclipse, right click the project → Close Project → right click project (again) → Open Project.

Android Studio

  1. In Android Studio, create a new Android project: File → New Project. The Application Name will be displayed to users, and the Module Name is used internally with Android Studio. Specify a package name ("com.myApp"), and set the Minimum SDK level to API 9 or greater. Set the Target SDK to your preferred platform level, and finally Compile With the highest API level available.
  2. Download the latest Kinvey library (zip) and extract the downloaded zip file.
    • copy all jars in the libs folder of the extracted zip to your project's libs folder on the file system, create the libs folder if it doesn't exist.
  3. After adding the jars, right click on kinvey-android-lib-x.x.x.jar and select Add As Library. Ensure your module is selected, and click OK.

Add an App Backend

If you don't have an account on Kinvey yet, please signup before continuing.

In the Kinvey console, click "New App" and enter the name of your app when prompted.

Add an app in Console

You can find your key and secret on the app backend dashboard page, or in the footer on every page.

Key and secret

Cut and paste the key and secret when performing the next steps.

Initialize a Client

The Client.Builder is used to build and initialize the Client before making any calls to the Kinvey API.

The Client.Builder requires the App Key and App Secret obtained from the Kinvey console, as well as your Android Application context. Initializing a Client is usually done within your application's main Activity.



final Client mKinveyClient = new Client.Builder(your_app_key, your_app_secret
    , this.getApplicationContext()).build();

For Dedicated Kinvey customers, you'll need to set the base URL for the library to your dedicated Kinvey host URL. You can find this host URL on the dashboard of the console, next to your App Key and App Secret:

final Client mKinveyClient = new Client.Builder(your_app_key, your_app_secret
    , this.getApplicationContext()).setBaseUrl("<your dedicated host URL>".build();

For push notifications you must use properties file initialization, see the next section for details.

Using a properties file

Hard wiring the appKey and appSecret programatically is a handy way for you to initialize the Kinvey library. However, this is not always the best choice. Often times you may want more control over the library config and would prefer to keep it in a separate properties file.

Your file in the assets folder of your project should contain the properties:

# Required settings

# Optional settings, only required for push

In order to initialize Client with the properties file settings you need to call a different constructor method on the Client.Builder class, then call build().

final Client mKinveyClient = new Client.Builder(this.getApplicationContext()).build();

Verify Set Up

You can use…) to verify that the app has valid credentials. The following code example:

  • builds a new client
  • pings the backend with the app credentials


final Client mKinveyClient = new Client.Builder(appKey, appSecret, this.getApplicationContext()).build(); KinveyPingCallback() {

    public void onFailure(Throwable t) {
        Log.e(TAG, "Kinvey Ping Failed", t);

    public void onSuccess(Boolean b) {
        Log.d(TAG, "Kinvey Ping Success");

Under most circumstances, the asynchronous API is what you want. You can use the synchronous API if you want fine-grained control over the execution of a particular service. If you use the synchronous blocking API, wrap all requests in asyncronous threads so as not to block Android's UI thread.

Every App has an Active User

Your app will be used by a real-life human being; this person is represented by the Active User. This user object must explicitly be created, either with a username and password, OAuth sign-on (such as Facebook, Google+, Twitter, etc.), or by using a utility method to auto-generate a username and password (for apps that don't need the user to log-in). See the User guide for more information.

What's next

You are now ready to start building your awesome apps! Next we recommend diving into the User guide or Data store guide to learn more about our service, or explore the sample apps to go straight to working projects.

Got a question?