Release NotesAnnouncementsBlogFAQSupport
Guides

Developer quick start: Clover Kiosk integration

Dual-screen architecture

Clover Kiosk operates as a unified system with two distinct displays powered by the Android system within Clover Mini. Your app should be cognizant of the UX state across both interfaces to ensure a smooth user experience:

  • 23.8-inch customer display: Your primary ordering app displays here. This is a portrait-mode, Full HD (1080x1920) interface.
  • 8-inch Clover Mini display: This acts as the payment terminal. Its primary purpose is to handle secure PIN entry and NFC or chip interactions. Your app uses the Android payments API intent builder to trigger a payment transaction flow.

Sandbox setup and testing

Because Clover Kiosk shares a dual-screen architecture with Clover Station Duo, developers can use a Station Duo to test their Clover Kiosk applications.

  • Test on Clover Station Duo: If you test your application on a Clover Station Duo, no special sandbox setup or permissions are required. Your app controls the larger display, while the customer-facing display processes the payment.
  • Test on Clover Kiosk: If you purchase and test on actual Clover Kiosk hardware, coordinate with Clover Developer Relations and Developer Programs teams to enable your app to support Clover Kiosk in both the sandbox and production environments.

Set up your development environment

Implement the Android payments API

Clover Kiosk uses the intent-based Android payments API. Instead of building a payment UI, your app uses the intent builder API to pass control to the Clover payment engine.

Ask for payments on the payment device:

  1. Create a KioskPayRequestIntentBuilder.
  2. Use the build(Context) method on the builder to get an intent.
  3. Start the activity for the result.
val builder = KioskPayRequestIntentBuilder(1250L, "<externalRefId>")
val intent = builder.build(context)
startActivityForResult(intent, REQUEST_CODE)

Disable partial payments

Partial payments are not supported by the native Clover Kiosk solution. Enforce this restriction in your integration using the KioskPayRequestIntentBuilder class. Call the setAllowPartialPayments() method on the builder and set its parameter to false to ensure an order is fully paid.

Application startup and device unlock

Launch the application automatically

Clover Kiosk automatically restarts during off-hours every day. Upon startup, the Clover Kiosk displays an unlock screen that requires an employee password. Configure your application to launch automatically after the startup process completes. This prevents users from seeing the Android launcher after the screen is unlocked.

Register a broadcast receiver for the BOOT_COMPLETED event in your application. Every time the device finishes the startup process, your broadcast receiver receives this information and starts its activity.

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<receiver
    android:name=".BootReceiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>
// BootReceiver.java
public class BootReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (Intent.ACTION_BOOT_COMPLETED.equals(intent.getAction())) {
            Intent i = new Intent(context, MainActivity.class);
            i.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
            context.startActivity(i);
        }
    }
}

Unlock the device screen automatically

Your application must unlock the device after the startup process completes. Unlock the device with a default employee or a specific employee. Both methods use the Clover Lockscreen class. Enable the Employee Read permission for your app to access functions that use values linked to employees.

  • Unlock with default employee: Use the unlock() or unlockDefault() function to unlock the device with the default employee. If you use the unlockDefault() function, the operation fails if the owner has not configured a default employee. Check whether a merchant has a default employee using the EmployeeConnector class before you call the unlockDefault() function.
  • Unlock with specific employee: Pass an employee ID to the unlock() function to unlock the screen with a specific employee. Use getEmployees() to receive the list of employee IDs.

User experience configuration

Use customer mode

When customer mode is enabled, your app runs full screen on the primary display without the navigation or status bar, and it prevents the customer from exiting your app. Provide a way to disable customer mode within your app when customer or merchant support is needed. Implement the Clover SDK in your project dependencies and use the CustomerMode class to enable or disable customer mode.

Keep the screen active

Clover devices enter sleep mode after about 30 minutes, as set in the Android settings. Configure the device to not enter sleep mode using the keepScreenOn property.

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:keepScreenOn="true">
</RelativeLayout>

Implement a splash screen or screen saver

Consider a home screen or screen saver for instances where the application is not used for an extended period.

  • Avoid excessive movement to minimize the use of the device processing power.
  • Limit idle time to about 15 minutes to avoid screen issues if you implement a static home screen.
  • Consider the screen brightness level depending on the environment where the Clover Kiosk is located.

Handle unexpected errors

Ensure the device is not vulnerable when the application is not in use. If the app encounters an unexpected error that it is not prepared to handle, disable customer mode and lock the device using the Lockscreen class.

// Example application error handling
public class KioskTestApp extends Application {
    private Thread.UncaughtExceptionHandler defaultUncaughtExcHandler;

    @Override
    public void onCreate() {
        super.onCreate();
        defaultUncaughtExcHandler = Thread.getDefaultUncaughtExceptionHandler();
        Thread.setDefaultUncaughtExceptionHandler((t, e) -> {
            CustomerMode.disable(this); // Disable customer mode
            new Lockscreen(this).lock(); // Lock device screen
            defaultUncaughtExcHandler.uncaughtException(t, e);
        });
    }
}

UI/UX asset requirements

Partners provide assets optimized for the following dimensions:

  • Ordering screen: 1080 x 1920 pixels (portrait).
  • Payment screen: 1280 x 800 pixels (landscape). The Clover app handles screens here.
  • Touch targets: Minimum 48dp x 48dp to ensure ease of use on the large vertical glass.

Print receipts

Clover Kiosk features an integrated thermal printer (80mm). Use the clover-android-sdk printer connectors to send print jobs. This is for printing custom receipts using the integrated printer and not Clover native receipts.

  • Formatting: Support for text, image-based branding (logos), and QR codes for digital receipts.

Checklist for testing

Before deployment, partners must verify:

  • Semi-unattended flow: Does the app time out and return to the Home screen if a user walks away?
  • Hardware failover: Does the app handle paper out or no internet (LTE failover) gracefully?
  • Accessibility: Is the app navigable via Google Talkback (using the 3.5mm audio jack)?

Kiosk UX best practices

Visual hierarchy and screen comfort zones

On a screen as large as 23.8 inches, users physically cannot see the entire display at once when standing close.

  • The middle-third rule: Keep the most frequent interactive elements (such as menu items and modifiers) in the middle third of the 23.8-inch screen to minimize uncomfortable reaching or crouching.
  • High-touch actions: Place critical navigation, like Back or Cancel, in consistent, reachable locations. This is typically the lower half of the large display.
  • Call to action (CTA): The primary Check Out or Pay button should be large, high-contrast, and located at the bottom of the large screen to lead the eye naturally toward the 8-inch Clover Mini display where payment happens.

Seamless dual-screen handshake

Prevent transaction friction by guiding the user's attention between the two devices.

  • Visual cues: When it is time to pay, the large screen should display a clear animation or arrow pointing toward the Clover Mini POS.
  • State mirroring: Ensure the order total is clearly visible on both screens during the final step, so the customer feels secure that the amounts match.
  • Status indicators: If the customer is using the Clover Mini POS for a PIN or signature, the large screen should display a "Processing..." or "Follow instructions on terminal" message to prevent other customers from thinking the Clover Kiosk is idle.

Optimized touch interaction

Kiosks are often used in high-traffic, rushed environments.

  • Generous targets: All buttons must be at least 48dp x 48dp (approximately 20mm) to prevent errors.
  • Eliminate manual text entry: Minimize the need for on-screen keyboards. Use quick-select buttons for common requests or quantities instead of manual text entry.
  • Immediate feedback: Ensure every touch provides visual feedback (such as buttons changing color or depressing), so the user knows the system registered their intent.

One-way transaction flow

To prevent user fatigue and confusion, the transition between the 23.8-inch display and the 8-inch Clover Mini display must be linear and definitive.

  • Clean flow transition: Keep all initial interactions, such as menu browsing, item customization, and order building, exclusively on the larger 23.8-inch display. Using the Clover Android payments API or SDK ensures this.
  • The payment handshake: When payment processing initiates, the user interactions are handed over to the Clover payments API or SDK, and a clear direction on the large screen displays stating "Continue on the PIN pad screen."
  • Avoid back-and-forth transitions: Once the interaction moves to the smaller payment screen, the experience should remain there until completion. Do not ask the user to return to the large screen for secondary tasks (like email entry for receipts) after they have already engaged with the payment terminal. This avoids a disjointed experience and keeps the customer focused on the hardware designed for secure input.

Error prevention and recovery

Unattended users can easily become frustrated if they make a mistake.

  • Linear progress: Use a progress bar at the top of the large display to show the customer exactly where they are in the ordering flow.
  • Easy edits: Allow users to modify items directly from the order summary without tapping the Back button multiple times.
  • Timeout safety: Implement a clear session timer that triggers if the screen isn't touched for a set period, but provide a "Still there?" countdown before wiping the cart to protect customer privacy.

Accessibility and compliance

As an integrator producing a public or consumer-facing application, additional attention should be paid to ensuring accessibility best practices are in place. The integrator is responsible for ensuring compliance with the Americans with Disabilities Act (ADA) and other usability standards.

By creating an application for consumer use, Clover expects integrators to implement at least Level A standards, and you need to confirm compliance before any Clover Kiosk application can be released on the Clover App Market.

  • Level A (minimum): Captions on images and video, reachable navigation options and on-screen keyboard, timing and timeouts, no rapid flashing, and no navigation traps.
  • Level AA (recommended): All of Level A plus a 4.5:1 color contrast ratio or better, consistent menu and navigation buttons, resizable text (up to 200%), and user-friendly error messages and handling instructions.
  • Level AAA (high standard): All of Levels A and AA plus ultra color contrast of 7:1 ratio or better, sign language provided on video content, no session timeout warnings (or very generous timeouts), and ultra-simplified written content.

Merchant locations are expected to implement a Clover Kiosk to the height and physical space requirements for consumers as outlined by the ADA.

Other resources

Updated about 2 hours ago