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.

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.