Overview

Clover devices run a custom version of the Android operating system (OS). You need to code apps for Clover devices to run on the Android OS. Clover provides support for multiple devices in multiple regions.

Support multiple devices

Clover has produced different device models over the years and continues to produce new devices. Consider supporting as many Clover devices as possible to reach the widest audience. You should understand the difference between compileSdkVersion, targetSdkVersion, and minSdkVersion. For more information, see:

• Clover devices
• Set up Android SDK versions
• Android Developers guide to support different screen sizes

Support multiple regions

Clover sells devices in a number of countries around the world, and this list may grow over time. Merchants and customers expect your application to support their language of choice, so we recommend that your application support the following languages: English, French, German, Spanish, and Dutch.

Differences between Android and Clover operating system

There are a few key differences between the Android-based operating system that runs on Clover devices and the Android OS that runs on off-the-shelf phones and tablets.

• Clover devices do not have Google Mobile Services (GMS) or the Google Play Store. This means you cannot use Google APIs on Clover devices, such as classes in packages like com.google.android.gms or com.google.firebase.
• Clover devices do not have Google bundled apps such as Chrome browser, Gmail, and YouTube.
• Announcements from Google regarding requirements for Play Store app submissions do not apply to Clover. For example, Google announcements regarding requirements for app target SDK levels do not apply to apps developed for Clover devices.
• Clover devices that use Android Marshmallow (API level 23) and later do not prompt for runtime permissions; instead, they grant permissions at install time only, just like earlier versions of Android.
• Clover devices include hardware components not typically found on off-the-shelf devices, such as receipt printers and payment interfaces. Clover offers special APIs for accessing these components that are not part of the standard Android SDK but are available through other SDKs, such as the clover-android-sdk.

Build Clover Android apps

Before you begin

1. Familiarize yourself with the process using Android Studio and the Android Emulator or an off-the-shelf phone.
2. See the standard Android documentation for an introduction to Android app development basics and advanced topics.
3. Use Java and Kotlin as the preferred languages for developing Android apps on Clover devices. Frameworks such as Flutter and React Native may work but are not recommended for use on Clover devices since they add a layer of complexity and will make it more difficult for Clover to support you.

Steps to build Clover Android apps

1. Download and install Android Studio.
2. Set up the emulator in Android Studio.
3. Associate your sandbox developer account with your Clover Dev Kits.
4. Create an app and make sure you request the permissions needed for your app to function.
   Note: To avoid confusing app users, do not use the term PIN in your app.
5. Build, install, and test your APK. Leverage the native Android buttons, such as the Back and Home buttons
6. Integrate with Clover Android SDK.
7. Call specific functions to retrieve API tokens and manage Clover merchant data.
8. Build payment solutions for accepting payments.
9. Collect and review metrics on your app's usage. You can review app usage patterns and continuously improve your app.

Developing for the Clover Kiosk

Clover Kiosk operates as a semi-attended system with a 23.8-inch primary ordering display and an 8-inch Clover Mini payment display. Your app will control the larger Kiosk display, while the customer-facing display processes the payment. Ensure your project targets Android 10.0 (API Level 29) and integrates the clover-android-sdk.

Sandbox setup and testing
Developers can build their app to run on a Station Duo to account for the larger display size.

• Testing on Station Duo: No sandbox setup via RM/DP is needed.
• Testing on Kiosk: If testing on a physical Kiosk device, coordinate with Developer Programs (DP) and Relationship Management (RM) to enable app support in both Sandbox and Production.

Application startup and device unlock
The Clover Kiosk automatically restarts during off-hours every day, displaying an unlock screen.

• Launch automatically: Register a broadcast receiver for the BOOT_COMPLETED event so your application launches automatically after the startup process completes.
• Unlock automatically: Your application must unlock the device after startup. Enable the Employee Read permission and use the Clover Lockscreen class to unlock the device with either a default employee (unlockDefault()) or a specific employee ID.

User experience configuration

• Customer mode: The device does not allow for merchant verification and interaction during transactions. Your app must run full screen on the primary display. Use the CustomerMode class to enable customer mode, and provide a secure way to disable it when merchant support is needed.
• Keep screen active: Configure the device to not enter sleep mode using the keepScreenOn property.
• Handle unexpected errors: If the app encounters an error, disable customer mode and lock the device using the Lockscreen class to ensure the terminal is not left vulnerable.

Implement the Android payments API
Instead of building a payment UI, use the KioskPayRequestIntentBuilder API to pass control to the Clover payment engine on the payment device. Partial payments are not supported natively; enforce this restriction by calling setAllowPartialPayments(false) on the builder.

Use device orientation

Device rotation in Clover devices

Clover devices without an owner won't respond to device rotation. You can change the rotation by programmatically setting the screen orientation. Hence, it is not recommended to use any of the sensor screen orientation modes.

Locked orientation

By default, apps that run on locked orientation on Clover devices use the default orientation and do not change with the sensed orientation. If you want to support screen rotation or use a different orientation mode, you must call it out explicitly in the manifest using the screenOrientation activity attribute.

<activity name="..."
  ...
  android:screenOrientation="sensor"
  ...
/>

You can alternatively set screen orientation at runtime.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(...);
   setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR);
}

Not locked orientation

Clover Station operates differently than other Clover devices. Screen orientation on the Station is not locked and is triggered by the swivel mount. It is not triggered by sensor orientation.

If your app supports Clover Station, make sure the app doesn't depend on the device's default screen rotation behavior. Rather, call out the screen orientation mode explicitly in your manifest or code to ensure proper operation on all Clover devices.

Handle background tasks and executors

When an app is launched, the system creates a thread of execution for the application called the main thread or UI thread. This thread dispatches events to the appropriate user interface (UI) widgets. It is usually the thread in which your app interacts with components from the Android UI toolkit packages: android.widget and android.view.

As a best practice, minimize or eliminate work on the main UI thread. See the Android documentation for best practices on running tasks in the background, such as Kotlin coroutines. For more information, see Asynchronous background processing.

Code securely

Do's

• Follow Clover guidelines for SSL/TLS.
• Follow SEI Cert Java Secure Coding Guidelines.

Don'ts

• Don't check app tokens into your source code online.
• Don't ask users to enter sensitive cardholder data, such as card numbers and expiration dates, except as part of Clover payments SDK. Third-party Clover apps are not payment apps as the term is defined in the PCI PA DSS). For more information, see Payment Card Industry security guidance for app developers.