Set up emulator in Android Studio

United States
Canada
Europe
Latin America

This topic covers the procedures that you need to complete to set up an Android Emulator for a Clover device.

Before you Begin

  • Review Custom Android basics for Clover devices.
  • Complete all the steps in the Android Emulator overview: Before you begin section.
  • Note that if you build an emulator for a device using an API level other than what this topic covers, the configuration may have minor Android-specific differences.

Watch video: Clover Android Emulator setup demo

Watch Learn

In this video, learn:

  • What are the prerequisites to install Android emulator?
  • How to download the Clover device profiles?
  • How to manage the emulator in the Device Manager?
  • How to work with device profiles? and more

Prerequisites

1. Download and extract Clover device profiles

Hardware profiles define the characteristics of a device as shipped from the factory. Clover maintains a profile of each device that you can import into the emulator.

  1. Download the Clover device profiles ZIP file.
  2. Extract the files to a location on your computer. You need to import the Clover device profiles into the Android Studio Device Manager.

2. Access Android Studio Device Manager

  1. Open Android Studio.
  2. To access the Device Manager, do one of the following on the Android Studio Welcome page:
  • Click the More Actions icon > Virtual Device Manager.
Android Studio: More Tools > click Virtual Device Manager

Android Studio: More Tools > click Virtual Device Manager

  • Open your app project, and on the project page, from the main menu, click View > Tool Windows > Device Manager.
Android Studio: Main menu > View > Tools window > click Device Manager

Android Studio: Main menu > View > Tools window > click Device Manager

3. Import Clover device profiles

  1. Open Android Studio and access the Device Manager.
  2. Click the + icon to Create Virtual Device. The Select Hardware page appears.
  3. At the bottom of the page, click Import Hardware Profiles.
  4. Browse to the folder where you downloaded the Clover device profiles and select the device profiles to import.
  5. Click Open. The selected Clover device profiles are imported into the Device Manager.
  6. On the Select Hardware page, in the search field, enter Clover. All Clover device profiles display in the Choose a device definition list.
  7. Select one or more Clover device profiles from the list and click Next. The System window page appears.
  8. Review the System information for the Clover device profile and click Next. The Verify Configuration page appears.
  9. Review or update the configuration information for the device profile and click Finish. The device profile displays on the Device Manager page.

You can now create a new emulator for the Clover device profile. See Set up an emulator in Android Studio.

4. Verify the DPI settings of the Clover device

Android runs on a variety of devices that have different screen sizes and pixel densities. The Clover Mini, Mini 2, Mini 3, and Mobile device profiles require a specific DPI that may be overridden if you make changes to the profile. To verify the DPI setting is correct, go to the Device Manager in Android Studio.

  1. Open Android Studio and access the Device Manager.
  2. Click the more icon next to the device profile, and from the menu click one of the following to view and verify the device profile DPI settings:
  • Click View Details. The device profile details display in the lower pane.
  • Click Show on Disk. The device details folder [user_home]/.android/avd/[virtual-device-name].avd displays on your computer. Search for and click the config.ini file. The file details display in Android Studio.
  1. To verify the DPI settings for the Clover Mini, Mini 2, Mini 3, and Mobile profiles, check the hw.lcd.density value is set to 213.

5. Run ADB as root

To use adb commands, you need install and properly configure Android Debug Bridge (ADB) on your computer. adb is included in the Android SDK Platform Tools package.

To verify that ADB can run as root, that is, it can execute commands with root-level permissions on an Android device or emulator:

  1. Open Android Studio and then open a project.
  2. From the main menu, click View > Tool Windows > Terminal. The Terminal window appears.
  3. In the Terminal window, run adb root. ADB is restarted to allow commands as root.
  4. Run adb shell id. A list of system IDs appears.
  5. Verify that the user ID uid value is 0(root).

Set up an emulator in Android Studio

1. Create a new emulator profile

Creating an emulator profile sets your emulator with the required device hardware configuration.

  1. Complete the steps to import Clover device profiles.
  2. Click the + icon to Create Virtual Device. The Select Hardware page appears.
  3. In the search field, enter Clover. All Clover device profiles display in the Choose a device definition list.
  4. Select a device profile from the list and click Next. The System Image page appears.
  5. Select the image for the API Level supported on the Clover device you are emulating.

Click to view: Clover devices with API level, ABI, and other information

Clover deviceRelease nameAPI levelABITarget
StationJelly Bean17x86Android 4.2
Mini 1
Mobile
KitKat19x86Android 4.4
FlexLollipop22x86Android 5.1
Station 2018Nougat25x86Android 7.1.1
Flex 2
Flex 3
Mini 2
Mini 3
Station Solo
Q/1029x86Android 10
  1. Click Next. The Verify Configuration page appears.
  2. Verify that the correct Startup orientation, landscape or portrait, is selected based on the device you are emulating.

Click to view: Clover device with Startup orientation information

Clover deviceStartup orientation
Flex
Flex 2
Flex 3
Portrait
StationLandscape
Mini 1
Mini 2
Mini 3
Mobile
Landscape
Station 2018Landscape
Station SoloLandscape
  1. Click Show Advanced Settings. Additional information displays on the page.
  2. Scroll down to the Memory and Usage section:
  • Set the RAM value based on the device you are emulating.
  • Set the Internal Storage value based on the device you are emulating:
    Note: Android Studio may reset the Internal Storage value to 800MB. Verify that the correct value is set so that you do not run out of storage space when installing the Clover apps.

Click to view: Clover device with RAM information

Clover deviceRAM (GB)
Station 20183 GB
Flex 2
Flex 3
Mini 1
Mini 2
Mini 3
Mobile
Station
Station Solo
2 GB
Flex1 GB

Click to view: Clover device with Internal storage information

Clover DeviceInternal storage (GB)
Flex
Station
5 GB
Mini 1
Mobile
6 GB
Mini 27 GB
Station 201810 GB
Flex 2
Flex 3
Mini 3
Station Solo
16 GB
  1. Click Finish. A new virtual device is added on the Device Manager page based on the Clover device profile you selected.
  2. Click the Launch icon for the device. The device emulator is launched.

2. Sideload the required Clover APK using ADB

Sideloading an APK using Android Debug Bridge (ADB) means installing an Android application package (APK) file directly to an Android device without using the Clover App Market. For Clover device emulators, you need to sideload certain Clover-specific APKs using ADB to fully simulate the Clover environment. With your device profile, install the Clover APK you need to configure the emulator. For more information, see Work with APKs.

  1. Open the Clover Development APKs page for the Clover environment on which you want to test:
  2. Download the Clover Engine APK (com.clover.engine-{version}.apk).
  3. Open Android Studio and then open a project.
  4. From the main menu, click View > Tool Windows > Terminal. The Terminal window appears.
  5. To verify that ADB is connected to the emulator, run the following command: adb devices. A response 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.
    A success message appears.

📘

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 and manage apps on the device emulator

1. Install required Clover merchant apps using Python

In this procedure, all Clover apps for merchants, such as Register, Orders, and Inventory, are installed on the virtual device by running a Python script. Any apps installed to the test merchant you select are also installed.

📘

NOTE

Python 3.5 or later is required to run the Python script. 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.

Add Clover as an account in the device emulator

  1. Open Android Studio and access the Device Manager.
  2. Search for the virtual device you want to start and click the Play icon next to it. The emulator runs the virtual device.
  3. From the emulator menu bar, click the more icon. The Extended controls window appears.
  4. Click Settings > Users & accounts. The Users & accounts page appears.
  5. Click Add Account. The Add an account** page appears.
  6. Click Clover. The Clover Developer Dashboard Login page appears.
  7. Log in to the Developer Dashboard and select a test merchant.

Download and run the app install script in Android Studio

  1. In Android Studio, from the main menu, click View > Tool Windows > Terminal. The Terminal window appears.
  2. 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: This step is not needed if you are setting up a second or subsequent emulator and have already downloaded the script.
  3. 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.
  4. In the terminal window, run adb reboot. The emulator reboots, and the Select a Home app pop-up appears.
  5. Select the Clover Launcher option and then click Always. The Clover homepage appears.

2. Install your test Android app

You can install your test Android apps once your initial emulator setup is complete.

  1. Log in to the Developer Dashboard.
  2. From the left navigation menu, click Your Apps > app name > Market Listing. The app name Market Listing page appears.
  3. Click Preview in App Market. The Merchant Dashboard for your test merchant account appears with an App Market preview of your app.
  4. Click Connect.
  5. On the Install app pop-up, select a pricing tier or accept the default, and then click Accept.
  6. 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...

3. 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. Open Android Studio and then open a project.
  2. From the main menu, click View > Tool Windows > Terminal. The Terminal window appears.
  3. If the emulator has not been restarted since the previous version of the APK was installed, run adb reboot. The emulator is restarted.
  4. 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...

4. Uninstall and sideload APKs

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

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

5. Update device settings for production testing

If you are testing your app in the United States (US) or European region production environment, you must change the Android device configuration before proceeding. Use the following steps for separate commands for the US and Europe.

  1. Open Android Studio and then open a project.
  2. From the main menu, click View > Tool Windows > Terminal. The Terminal window appears.
  3. 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"
  • Europe: adb shell settings put secure clover_cloud_url "https://www.eu.clover.com"
  1. Run one of the following commands to set the clover_target:
  • US: adb shell settings put secure clover_target "prod_us"
  • Europe: adb shell settings put secure clover_target "prod_eu"

Related topics