Watch a Clover Android emulator setup demo

Click the play button below to learn how to set up a Clover Android emulator.

Set up an Android Studio emulator

You can setup an Android Studio emulator to develop apps on the Clover platform. After you set up the emulator per the device's hardware profile, you can use it to quickly prototype, develop, and test your Clover applications.

The steps in this page are written for the following operating systems:

• Android Oreo (API level 27), the operating system used by Clover Flex 2 and Clover Mini 2
• Android 10 (API level 29) for Clover Mini 3 and Clover Flex 3.

If you are building an emulator for a device using an earlier API level, there may be minor Android-specific differences in configuration.

When possible, we recommend using a Clover Developer Kit (Dev Kit) to fully test your user experience. Many applications can be developed on an emulator—but, there are exceptions. With Dev Kits, you have access to hardware-specific functionalities such as:

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

Before you get started

• Emulator requirements
• Emulator limitations

🚧

IMPORTANT

You cannot emulate the Station Duo or Duo 2, as they are a combination of two devices—Terminal and Display.

Download Clover hardware profiles

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

1. Download the clover-device-profiles.zip archive.
2. Extract the files to a location of your choosing.

📘

NOTE

The hardware profiles for the Clover Mini, Mini 2, Mini 3, 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 > Device 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.

Create 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 > Device Manager. The Android device manager window appears.
3. Click the Virtual tab and then click Create device.
4. On the Virtual Device Configuration window, click Import Hardware Profiles.
5. Navigate to the Clover hardware profiles you downloaded, select one or more files, and then click OK.
6. In the search box, type Clover.
7. Select the device profile you want to use and then click Next.
8. 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.

📘

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.

8. On the Verify Configuration page, verify that the correct Startup orientation is selected:

9. Click Show Advanced Settings.
10. Set the RAM value to the amount for the device you are emulating:

11. Set the Internal Storage value to the amount for the device you are emulating:

📘

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.

12. Click Finish. A new virtual device is added.
13. In the Actions column for the device, click the Launch icon. The emulator is launched.

📘

NOTE

The hardware profiles for the Clover Mini, Mini 2, Mini 3, 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 > Device 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.

Update 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 before proceeding. 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"

Sideloade the required Clover APK using ADB

With your emulator profile set, install the Clover APK needed to configure the emulator.

1. Open the Clover Development APKs page for the Clover environment you want to test against:
   • Sandbox
   • Production (US)
   • Production (EU)
2. Download the Clover Engine APK (com.clover.engine-{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

5. To install the Clover Engine APK, run adb install {download_folder}/com.clover.engine-{version}.apk.
   A Success message appears. Leave the terminal window open.

📘

NOTE

ADB must be able to run as root. To verify this, complete the following steps.

1. In the terminal window, run adb root.
   ADB is restarted to allow commands as root.
2. Run adb shell id.
   A list of system IDs appears.
3. Verify that the uid value is 0(root).

📘

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.

Install required Clover merchant apps

In this setup step, all Clover apps for merchants (such as Register, Orders, and Inventory) are installed by running a Python script. Any of your apps installed to the test merchant you select will also be installed.

📘

NOTE

Python 3.5 or later is required to run the Python script.

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 owner account 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. In the terminal window, run the following command to download the app install script to the current directory: curl https://raw.githubusercontent.com/clover/clover-android-sdk/master/scripts/install_apps.py -O. Note that this step is not necessary if you are setting up a second or subsequent emulator and have already downloaded the script.

7. Run the install script (./install_apps.py) and wait for all of the apps to be installed. You may need to change the access permissions to make the file executable for your user.

📘

NOTE

If your machine falls back on Python 2 as a default, you may need to use the pip3 and python3 commands to install the required modules and run the script. urllib3 is a required module for the script.

8. In the terminal window, run adb reboot.
   The emulator reboots and the Select a Home app dialog appears.
9. Select the Clover Launcher option and then click Always.
   The Clover home screen appears.

Install your test Android app

Once your initial 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.
4. On the Install app dialog, select a pricing tier or accept the default, and then click Accept.
5. In the terminal window, run the install script (./install_apps.py).
   Your app is downloaded and installed on the emulator.

$ ./install_apps.py
Getting installed versions...
Getting current app data...
Updating package: your.package.name from version: ?, to version: 1...

Install new versions of your app

Emulators do not function exactly like Clover devices, so the app update process is not automatic. After you've uploaded a new APK on the developer dashboard, complete the following steps to update the APK installed on the emulator.

1. In Android Studio, select View > Tool Windows > Terminal (Alt+F12/Option+F12).
2. If the emulator has not been restarted since the previous version of the APK was installed, run adb reboot.
   The emulator is restarted.
3. Run the install script (./install_apps.py).
   The new APK is downloaded and installed on the emulator.

$ ./install_apps.py
Getting installed versions...
Getting current app data...
Updating package: your.package.name from version: 1, to version: 2...

Sideload APKs

You can also sideload APKs to your emulator, but you must first uninstall the previous version manually with adb uninstall your.package.name. When updating to a new version of your app, the new version must be installed using the same method (the install script or sideloading) as the previous version. If you try to use the other method, Android's signature verification will return an error:

Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE: 
Package your.package.name signatures do not match
the previously installed version; ignoring!]