Platform Docs

Emulator Setup in Android Studio

Overview

We recommend using a Clover Developer Kit (or DevKit) to fully test your user experience. This will also allow you to access hardware-specific functionality like NFC, other secure payments, printing, and scanning. However, if you are not relying on those functionalities, it is also possible to use an emulator to quickly prototype, develop, and test your Clover applications.

NOTE

This page documents the process of setting up an emulator in Android Studio for developing apps on Clover Mini (2nd generation) i.e. Android Oreo (API level 27). For earlier API levels, there may be minor Android-specific differences in configuration.

Download Clover hardware profiles

Clover maintains a profile of each device that you can import into the emulator.

  1. Open the Emulator Hardware Profiles page.
  2. Copy and save the profile of each device you want to emulate:
    • clover-mini-2nd-gen.xml
    • clover-station-2018.xml
    • clover-flex.xml
    • clover-mini.xml
    • clover-mobile.xml
    • clover-station.xml

Create a new emulator profile

By creating an emulator profile, your emulator is set with the required hardware configuration.

  1. Launch Android Studio.
  2. Select Tools > AVD Manager. The Android virtual device manager window appears.
  3. Select Create Virtual Device.
  4. On the Virtual Device Configuration modal, select Import Hardware Profiles.
  5. Navigate to the Clover hardware profile you downloaded, select it, and then select OK.
  6. From the Tablet category, select your Clover profile, and then select Next.
  7. On the System Image page, select the image for the API Level supported on the Clover device you are emulating (based on the following table), and then select Next.
Clover device
Release name
API level
API
Target

Station

Jelly Bean

17

x86

Android 4.2

Mobile/Mini (1st gen)

KitKat

19

x86

Android 4.4

Flex

Lollipop

22

x86

Android 5.1

Station 2018

Nougat

25

x86

Android 7.1.1

Mini (2nd gen)

Oreo

27

x86

Android 8.1

NOTE

You may be required to select the x86 Images tab to find the Android release version needed for your emulator. If the system image is not already available locally, select Download and install the image.

Download a system image without the Google APIs. Clover devices are not Google Play certified and therefore do not come with Google Play Services.

NOTE

With Android 6.0, grant at runtime permissions have been introduced, which enables users to grant permissions to apps while the app is running, not when they install the app.

If you are developing on a Clover emulator, target API 21 or lower. This will use the grant at install permission model that is followed by Clover devices.

If you target API 23 or above and implement the grant at runtime flow, the same application will run correctly on Clover devices without modification.

  1. On the Verify Configuration page, verify that the correct Startup orientation is selected:
Clover device
Startup orientation

Station

Landscape

Mobile/Mini (1st gen)

Landscape

Flex

Portrait

Station 2018

Landscape

Mini (2nd gen)

Landscape

  1. Select Show Advanced Settings.
  2. Set the RAM value to the amount for the device you are emulating:
Clover device
RAM (GB)

Station

2

Mobile/Mini (1st gen)

2

Flex

1

Station 2018

3

Mini (2nd gen)

2

  1. Set the Internal Storage value to the amount for the device you are emulating:
Clover Device
Internal storage (GB)

Station

5

Mobile/Mini (1st gen)

6

Flex

5

Station 2018

10

Mini (2nd gen)

7

  1. Select Finish. A new virtual device is added.
  2. In the Actions column for the device, select the Launch icon. The emulator is launched.

NOTE

The hardware profiles for the Clover Mini, Mini 2nd Gen, and Mobile require a specific DPI that may be overridden if you make changes to the profile. To verify the setting is correct:

  1. In Android Studio, select Tools > AVD Manager.
  2. In the Actions column for the device, select View Details from the list.
  3. In the details modal that appears, ensure that the hw.lcd.density value is set to 213.

You can also verify this by opening the [user_home]/.android/avd/[virtual-device-name].avd/config.ini file.

Install required Clover APKs using ADB

With your emulator profile set, install the 2 required Clover APKs for the emulator to launch apps.

  1. Open the Clover Development APKs page.
  2. Select to download the following APKs: com.clover.engine-[version].apk and com.clover.appupdater-<version>.apk.
  3. In Android Studio, select View > Tool Windows > Terminal (Alt+F12/Option+F12).
  4. To verify that ADB is connected to the emulator, run the following command: adb devices. A response like the following appears:
List of devices attached
emulator-5554    device
  1. To install the Clover Engine APK, run adb install [download_folder]/com.clover.engine-[version].apk.
  2. To install the Clover App Updater APK, run adb install [download_folder]/com.clover.appupdater-[version].apk. A Success message appears for each APK. Leave the terminal window open.

Configure the emulator to run as a Clover device

Once you have installed the APKs, set up the Clover system account and set the Clover launcher as the home application.

  1. On the emulator, open Settings.
  2. Select Users & accounts > Add Account.
  3. On the Add an account page, select Clover.
  4. On the LOG IN page, enter your sandbox developer credentials, and select Log In. If you have created multiple test merchants for your developer account on sandbox, select the merchant you want to test with from the window that appears.
  5. In the terminal window, run adb reboot.

The emulator reboots. When the emulator powers on, the Clover base apps are synced to the emulated device. This process may take several minutes as all of the apps are downloaded. Download progress can be seen in the Clover App Updater notification. Wait until the notification says Updates are installing.

Install required Clover merchant apps

In this setup step, all Clover apps for merchants, such as Register, Orders, and Inventory, are installed.

  1. On the emulator, select the Clover App Updater notification from the notification bar. The App Updater app opens and lists the number of updates available.
  2. Select Install Now.
  3. For each app, scroll to the end of the permissions list and then select Install.
  4. Return to Settings on the emulator.
  5. In the Device section, select Apps.
  6. In the upper-right corner, select the Configure Apps icon (gear icon).
  7. On the Configure Apps page, select Home app.
  8. On the modal, select Launcher. The Clover Launcher is set as the home app.

Install your test Android app

Once your emulator setup is complete, you can install your test Android apps.

  1. On the Developer Dashboard, select Preview in App Market for your test app. The Merchant Dashboard appears with the App Market preview.
  2. Select Connect. The app is automatically downloaded and installed on the emulator.