Custom Android basics for Clover devices

United States
Canada
Europe
Latin America

Get started

Clover devices run a custom version of the Android operating system. Apps that run on Clover devices must be written to run on the Android operating system.

If you have never developed a standard Android app before we suggest you familiarize yourself with the process using Android Studio and the Android emulator or an off the shelf phone. Take a look at the standard Android documentation for an introduction to Android app development basics and advanced topics as well.

The preferred languages for developing Android apps on Clover devices is Java and Kotlin. Frameworks such as Flutter and React Native may work but are not recommended for use on Clover devices since they add an additional layer of complexity and will make it more difficult for Clover to provide you with support.

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.
  • Google bundled apps such as Chrome browser, Gmail and YouTube are not available on Clover devices.
  • Any 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 does not apply to apps developed for Clover devices.
  • Clover devices which are marshmallow (API level 23) and above do not prompt for runtime permissions, instead they grant permissions at install time only just like older versions of android.
  • Clover devices include hardware components that are not typically found on off-the-shelf devices such as a receipt printer 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.

Support multiple devices

Clover has produced a variety of devices 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. Our current oldest supported device (the original Clover Station) runs Android API level 17. See the Clover devices page for information about all the Clover devices. See our advice on Setting Android SDK versions for more information specific to Clover devices.

Google has numerous tips to help you ensure that your apps run properly on a variety of 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 your application support the following languages—English, French, German, Spanish and Dutch.

Build Clover Android apps

  1. Download and install Android Studio.
  2. Set up the emulator in Android Studio.
  3. Associate your sandbox developer account to your Clover Dev Kits.
  4. Create a sandbox app and make sure you request the permissions needed for your app to function
  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 apps usage. You can review app usage patterns and continuously improve your app.

To avoid confusing consumers, do not use the term PIN in your app.

Device Rotation

ModelDefault OrientationOrientation ModeOrientation Sensor
StationLandscapeNot LockedYes (hinge)
Mobile, Mobile 3GLandscapeLockedYes
Mini, Mini 3G, Mini 2018 LTE), Mini EnterpriseLandscapeLockedNo
Flex, Flex LTE (4G) or Europe 3G, Argentina 3G, Flex (2nd Generation)PortraitLockedYes
Station 2018LandscapeLockedYes
Station Pro, Clover Station TerminalLandscapeLockedNo

Clover devices that don't have an orientation sensor won't respond to device rotation. You can change the rotation by setting the screen orientation programmatically. Hence, it doesn't make sense to use any of the sensor screen orientation modes.

Locked Orientation

By default apps that run on locked orientation Clover devices will orient according to the default orientation, and will 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 Station is supported by an app, make sure the app doesn't depend on the default screen rotation behavior of the device. Rather, call out the screen orientation mode explicitly in your manifest or code to ensure proper operation on all Clover devices.

Async Tasks and Executors

  • Minimize or eliminate work on the main UI thread.
  • Verify that your activity is not finished or destroyed upon completion of an Async Task’s background task.

Security

Do's

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 Clovers payments SDK. Third-party Clover Apps are not payment apps as the term is defined in the PCI PA DSS).