Create your first Clover app

Overview

This tutorial will walk you through the process of creating a simple Android app using the Clover platform. It assumes you have the following:

  • A Clover developer account.
  • A Clover DevKit (recommended) or emulated virtual device.
  • A working Android development environment, such as Android Studio.
  • Basic knowledge of Android development. If you’re just getting started, Android has excellent documentation.

Note

The tutorial uses the following setup:

  • JVM 1.8.0
  • Gradle 2.3
  • Android Studio 1.2.1.1

Generate your app

To prepare for developing a Clover app, generate a basic APK and register your app with the Clover platform.

  1. Create a new project in Android Studio. This tutorial uses the Blank Activity template. Set the minimum SDK to 17 and enter a package name. Note that the name of the package cannot begin with “clover.” Before making any other changes to the app, generate a signed APK of the new project. You may also want to review the requirements for Clover APKs.

    Note

    Before you can sideload your app onto your device for testing, you must upload your APK to the Clover App Market, then download it onto your device. You will only need to do this once. Afterwards, you’ll be able to sideload new versions of your app onto the device directly.

    Important

    When signing your app in Android Studio, make sure your APK is signed with the V1 (Jar Signature) Signature Version only. V2 (Full APK Signature) is not supported.

  2. Create your app on the Developer Dashboard.Create New App
  3. On the dashboard’s Edit App page, add the Merchant and Inventory Read permissions. You will use these permissions for this tutorial.Permissions

    Note

    If you change app permissions after a merchant (including your test merchant) has downloaded it, the new permissions will not take effect for that merchant unless the merchant uninstalls and reinstalls the app.

  4. Add price(s). An app requires at least one pricing option before merchants, including your own test merchants, can install and launch the app. From the Developer Dashboard, click on Edit Pricing to launch and complete this step.
  5. Navigate to the Manage APKs page and upload your signed APK.

    Important

    Once you’ve successfully uploaded the first APK for an app, all future APKs for that app must have the same package name and an incremented versionCode.

  6. Open the App Market on your Clover device and locate your app. You will see the status “Not Published” at the top-right corner of the card for the app. Your unpublished app will only be visible to the merchant accounts associated with your developer account.Download App from App Market
  7. Install the app.
  8. Launch the app on your device. You should see the default “Hello world!” layout. After completing these steps, you will be able to sideload new versions of the app directly onto this device.Hooray!

Integrate with the Clover Android SDK

Use the Clover Android SDK to access merchant data. For this example, we will display information on one inventory item.

Note

For this tutorial, you must have one item in your merchant’s inventory. You can do this through the Inventory app.Bottled Water

  1. Add a dependency for the latest version of the Clover Android SDK to the gradle.build file for your app’s module.

    Important

    Adding this dependency with the following code will always pull the latest released version of our Clover SDK.

    dependencies {
    compile 'com.clover.sdk:clover-android-sdk:latest.release'
    }

    Your gradle.build file should look like the file in the image below.

    Add dependency

  2. Add <uses-permission android:name="android.permission.GET_ACCOUNTS"/> to the AndroidManifest (this is required to connect with the merchant account).use GET_ACCOUNTS permission
  3. Add an ID to the textView element to enable dynamic text insertion.TextView with ID
  4. Finally, you can replace your Activity with this code to pull out the merchant data:
    package com.your.package.name.here;
    
    import android.accounts.Account;
    import android.os.AsyncTask;
    import android.os.RemoteException;
    import android.os.Bundle;
    import android.support.v7.app.AppCompatActivity;
    import android.widget.TextView;
    
    import com.clover.sdk.util.CloverAccount;
    import com.clover.sdk.v1.BindingException;
    import com.clover.sdk.v1.ClientException;
    import com.clover.sdk.v1.ServiceException;
    import com.clover.sdk.v3.inventory.InventoryConnector;
    import com.clover.sdk.v3.inventory.Item;
    
    
    public class MainActivity extends AppCompatActivity {
    
        private Account mAccount;
        private InventoryConnector mInventoryConnector;
        private TextView mTextView;
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    
        @Override
        protected void onResume() {
            super.onResume();
    
            mTextView = (TextView) findViewById(R.id.activity_main_text_view);
    
            // Retrieve the Clover account
            if (mAccount == null) {
                mAccount = CloverAccount.getAccount(this);
    
                if (mAccount == null) {
                    return;
                }
            }
    
            // Connect InventoryConnector
            connect();
    
            // Get Item
            new InventoryAsyncTask().execute();
        }
    
        @Override
        protected void onDestroy() {
            super.onDestroy();
            disconnect();
        }
    
        private void connect() {
            disconnect();
            if (mAccount != null) {
                mInventoryConnector = new InventoryConnector(this, mAccount, null);
                mInventoryConnector.connect();
            }
        }
    
        private void disconnect() {
            if (mInventoryConnector != null) {
                mInventoryConnector.disconnect();
                mInventoryConnector = null;
            }
        }
    
        private class InventoryAsyncTask extends AsyncTask<Void, Void, Item> {
    
            @Override
            protected final Item doInBackground(Void... params) {
                try {
                    //Get inventory item
                    return mInventoryConnector.getItems().get(0);
    
                } catch (RemoteException | ClientException | ServiceException | BindingException e) {
                    e.printStackTrace();
                }
                return null;
            }
    
            @Override
            protected final void onPostExecute(Item item) {
                if (item != null) {
                    mTextView.setText(item.getName());
                }
            }
        }
    }

Now you can sideload your app onto your device to see it in action.Finished App

Next steps

Now that you’ve built your first native Clover app, we encourage you to jump into the rest of the Clover developer resources.