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.

Prerequisites

• Java Development Kit (JDK) 1.6
• Android SDK simply follow the installation instructions. This library currently supports Android 2.3 and higher.
• Eclipse and ADT Plugin installed which ships with Android SDK r21 and higher

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
3. In Eclipse, right click the project → Close Project → right click project (again) → Open Project.

Add an App Backend

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

You can find your key and secret on the app backend dashboard page.

Cut and paste the key and secret when performing the next step, Initialize Client.

Initialize 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.

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

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 kinvey.properties file in the assets folder of your project should contain the properties:

# Required settings
app.key=your_app_key
app.secret=your_app_secret

# Optional settings, only required for push
push.key=your_push_key
push.secret=your_push_secret
push.mode=debug

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 Client.ping() to verify that the app has valid credentials. The following code example:

• creates an implicit user
• stores the implicit user credentials securely
• pings the backend with the implicit user credentials

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

mKinveyClient.user().login(new KinveyUserCallback() {

    @Override
    public void onFailure(Throwable error) {
        Log.e(TAG, "Login Failure", error);
    }

    @Override
    public void onSuccess(User result) {
        Log.i(TAG,"Logged in successfully as " + result.getId());
        mKinveyClient.ping(new KinveyPingCallback() {

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

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

    }

});

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. When the app launches the active user will be unset. The first call to the backend (whether that's a ping, query, or any action that requires an active user) will attempt to restore the active user from the credentials saved in the keychain. If there is not a saved user, an implicit user will be created automatically. 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.