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

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.

• Open your app project, and on the project page, from the main menu, click View > Tool Windows > 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.

3. 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

The Android Debug Bridge (ADB) is a command-line tool that lets you communicate with an emulator instance or connected Android device. It's included in the Android SDK Platform-Tools package, which you can download from the Android SDK Manager. To use adb commands, you need install and properly configure ADB on your computer.

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.

6. Click Next. The Verify Configuration page appears.
7. Verify that the correct Startup orientation, landscape or portrait, is selected based on the device you are emulating.

8. Click Show Advanced Settings. Additional information displays on the page.
9. 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.

10. Click Finish. A new virtual device is added on the Device Manager page based on the Clover device profile you selected.
11. 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 simulate the Clover environment fully. 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:
   • Sandbox
   • Production: Europe
   • Production: Latin America
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

6. 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. On the virtual device, click the Settings app.
4. Enter Account in the Search field and click Accounts. The Add an Account page appears.
5. Click Clover. The Clover Developer Dashboard Login page appears.
6. 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 Virtual 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 Virtual 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 you have not restarted the emulator since installing the previous version of the APK, 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 using 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 returns 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"

4. 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"

Delete a virtual device from the Android Emulator

You can delete data, such as sensitive information, from a virtual device or permanently delete the virtual device. Clover recommends backing up any app data, system settings, and user profiles before wiping data or deleting a virtual device. Use the adb pull command to copy files or directories from the virtual device to your local system. For example, to back up a file located at /data/data/com.example.myapp/myfile, use the command adb pull /data/data/com.example.myapp/myfile ./, where ./ is the destination on your local system.

To wipe data or delete a virtual device:

1. Open Android Studio and access the Device Manager. A list of available virtual devices appears.
2. Click the ⋮ more icon next to a virtual device, and from the menu, click one of the following:
   • Wipe Data to delete all user profiles and information from the virtual device. This ensures that all sensitive data and test information is deleted.
   • Delete to permanently delete the virtual device and all its information from the emulator.
3. Click Yes on the confirmation message pop-up.
4. To turn off a running Android Emulator, close the emulator window.

Related topics

• Android Emulator overview
• Work with APKs
• Manage your APKs
• Integrate with Clover Android SDK
• Troubleshoot emulator issues