Create Your First Clover App

Overview

This tutorial walks through the process for creating a simple Android app using the Clover platform. It is assumed that you have the following:

Note

Setup used for this tutorial:

  • JVM 1.8.0
  • Gradle 2.3
  • Android Studio 1.2.1.1

Generate App

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

  1. In Android Studio, create a new project (I am using the ‘Blank Activity’ template), set the minimum SDK to 17, and use a package name of your choice, as long as it doesn’t begin with ‘clover’. Before making any other changes to the app, you can generate a signed APK of the new project. Now is a good time to read about the requirements for Clover APKs.

    Note

    Before you can sideload your app onto your device for testing you must upload your APK and download it onto your device via the App Store. Once you do this once, it will be possible to sideload new versions of your app onto the device directly for testing.

    Important

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

  2. Create your app on your Developer Dashboard.Create New App
  3. In the dashboard’s Edit App page, add the Merchant Read and Inventory Read permissions, which we will be using for this tutorial.Permissions

    Note

    If you change the permissions required for an app after a merchant (including your test merchant) has downloaded it, the new permissions will not take effect for that merchant until they uninstalled and re-install it.

  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 the Edit Pricing link to launch and complete this step.
  5. On the dashboard’s Manage APKs page upload your signed APK.

    Important

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

  6. On your Clover device locate your app in the App Market. It will be marked as ‘Not Published’, and will only be visible in the App Market for the merchant accounts associated with your developer account.Download App from App Market
  7. Install the app, find the app icon on the device’s main menu, and launch it. You should see the default ‘Hello World!’ layout. From now on it will be possible to sideload new versions of this app directly onto this device.Hooray!

Integrate with Clover Android SDK

Use the Clover Android SDK to access merchant data. For this example, we will be displaying the name of one of the merchant’s inventory items.

Note

For this tutorial, you must have one item in your merchant’s inventory. This can be done so by adding at least one item via 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

    This will always pull the latest released version of our Clover SDK.
    dependencies {
    compile 'com.clover.sdk:clover-android-sdk:latest.release'
    }

    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 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: