Platform Docs

Emulator setup on Android Studio

Overview

We recommend using a Clover Developer Kit (or DevKit) to fully test your user experience. With DevKits, you have access to hardware-specific functionalities, such as:

  • NFC and Bluetooth Low Energy (BLE)
  • Secure payments
  • Printing
  • Scanning

As another option, you can set up an Android emulator and quickly prototype, develop, and test your Clover applications. While using an emulator is cost-effective, you will not have access to hardware-specific functionalities that DevKits can provide.

NOTE

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

Downloading 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-flex-2nd-gen.xml
    • clover-mini-2nd-gen.xml
    • clover-station-2018.xml
    • clover-flex.xml
    • clover-mini.xml
    • clover-mobile.xml
    • clover-station.xml

Creating a new emulator profile

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

  1. Launch Android Studio and open your app's project if it does not load automatically.
  2. Select Tools > AVD Manager. The Android virtual device manager window appears.
  3. Click Create Virtual Device.
  4. On the Virtual Device Configuration window, click Import Hardware Profiles.
  5. Navigate to the Clover hardware profile you downloaded, select it, and then click OK. If the profile does not appear, click Refresh.
  6. From the Tablet category, select your Clover profile, and then click 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 click 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

Flex (2nd gen)/Mini (2nd gen)

Oreo

27

x86

Android 8.1

NOTE

You may need to click the x86 Images tab to find the Android release version needed for your emulator. If the system image is not already available locally, click 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 (API level 23), 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.

Clover devices follow the grant at install app permission model. This model enables Clover merchants to grant device permissions to apps as part of the installation.

To use the grant at install app permission model on the emulator, set the target SDK level to 22 or lower. If your app requires target SDK level 23, 24, or 25, implement the grant at runtime model to have your app run correctly on the emulator. On Clover devices, this model is overridden and your app follows the grant at install model.

  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

Flex (2nd gen)

Portrait

  1. Click 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

Flex (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

Flex (2nd gen)

16

NOTE

Android Studio may reset the Internal Storage value to 800MB. Verify that the value is set correctly or you will run out of storage space when installing the Clover apps.

  1. Click Finish. A new virtual device is added.
  2. In the Actions column for the device, click 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.

Sideloading required Clover APKs using ADB

With your emulator profile set, install the two Clover APKs needed for the emulator to launch apps.

  1. Open the Clover Development APKs page for the Clover environment you want to test against:
  2. 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.

NOTE

The next time you sideload an app, open a Clover app and then click the sync button at the top-left of the app. This ensures that you have the latest version of your sideloaded app on the emulator.

Installing 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, open Settings.
  2. Click Users & accounts.
  3. On the Users & accounts page, click Add Account.
  4. On the Add an account page, click Clover.
  5. On the LOG IN page, enter your developer credentials, and click Log In. If you have created multiple test merchants for your developer account, select the merchant you want to test with from the window that appears.
  6. On the Users & accounts page, click Add Account.
  7. On the Add an account page, click App Updater.
  8. On the Accounts page, click the App Updater row that appears.
  9. On the App Updater page, click Account sync.
  10. Click the toggle to enable syncing.
  11. Pull down the notification bar and click the App Updater notification.
  12. On the App Updater page, click Install Now and wait for all of the apps to download.
    An App Updater dialog appears warning you about unknown app installation.
  13. On the dialog, click Settings.
  14. On the Install unknown apps page, click the Allow from this source toggle.
  15. In the terminal window, run adb reboot.
    The emulator reboots and the Clover app permissions page appears.
  16. To accept the permissions request and install the app, click Install.
    The app is installed and an app permissions page appears for the next app.
  17. Repeat the previous step until all the apps are installed.
    The App Updater closes and the Android home screen appears.

Configuring 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. Click Apps & notifications.
  3. Select Advanced > Default Apps.
  4. On the Default Apps page, click Home app.
  5. On the Home app page, select Launcher.
    The Clover Launcher is set as the home app.
  6. Click the home button.
  7. If your merchant requires a device passcode, enter the passcode.
  8. On the LOG IN page, enter your developer credentials, and click Log In. If you have created multiple test merchants for your developer account, select the merchant you want to test with from the window that appears.
    The Clover home screen appears.

Installing your test Android app

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

  1. On the Developer Dashboard, click Market Listing on the side-nav.
  2. On the Market Listing page, click PREVIEW IN APP MARKET. You are redirected to the Merchant Dashboard for your test merchant account with an App Market preview of your app.
  3. Click Connect. The app is automatically downloaded and installed on the emulator.

Updating device settings for production testing

If you are testing your app against the US or EU production environment, you must change the Android device configuration. Each of the following steps provides separate commands for the US and EU.

  1. In the terminal window, run one of the following commands to set the clover_cloud_url:
    • US: adb shell settings put secure clover_cloud_url "https://www.clover.com"
    • EU: adb shell settings put secure clover_cloud_url "https://www.eu.clover.com"
  2. In the terminal window, run one of the following commands to set the clover_target:
    • US: adb shell settings put secure clover_target "prod_us"
    • EU: adb shell settings put secure clover_target "prod_eu"

Emulator setup on Android Studio


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.