Developer Guidelines

Welcome to the Clover App Market, the world’s largest point of sale app platform. As a third party developer, your apps can add functionality and address new use-cases for the rapidly expanding Clover merchant community.

The following guidelines are designed to help you produce high quality apps, with a smooth development and launch process. These foundations can help your apps provide the kind of excellent merchant experiences that attract and keep loyal subscribers.

Hardware

Overall Best Practices

  • Create a Clover Developer Account (US App Market, EU App Market), and familiarize yourself with our Developer Agreement and Launch Checklist before submitting your app.
  • Your app should respond to the needs of Clover merchants.
  • Your app must comply with Clover’s App Market Policies
  • Thoroughly test your app prior to submission. Apps that do not function as expected will be rejected.
  • Ensure that any externally generated data is correctly syncing with the Clover platform.
  • Outside of login credentials, do not require users to manually input data that is already accessible to your app via the Clover APIs.
  • Design around Clover’s modules and merchant plans.
  • Your app should have a good end to end experience. Apps that do not have a significant and reasonable amount of functionality may be rejected during the review process.
  • You should use Clover data objects and representations within your app and keep them synchronized with Clover services.
  • You must authenticate with Clover using OAuth tokens, use of testing or other tokens will subject your app to removal.

API Usage

Security

  • Protect sensitive customer and employee data.  Do not publicly expose names, addresses, or phone numbers.
  • Never expose auth tokens, or passwords of any kind.

Money Calculations

  • Tax should be calculated using the algorithm described here.
  • Monetary values are always passed as longs, representing the smallest denomination of the merchant’s currency.

Rate Limiting

  • If your app or service must trigger requests from multiple merchants, these requests should be staggered as much as possible to avoid bursts of high traffic volume.
  • Use WebHooks to trigger updates, and avoid constant polling.
  • Cache your own data when you need to store specialized values, or rapidly review very large data sets.
  • Handle 429 error codes (rate limit reached) by responding with an exponential back-off.
  • If you need to backfill data, it is best to do so during non-peak business hours.
  • We maintain two rate limits on Apps to ensure quality of service for both merchants and developers.
    • We maintain a rate limit of 16 requests per second for each token.
    • Apps also have a cross token total rate limit of 50 requests per second.
    • If your product requires more capacity, please contact us at appmarketbusiness@clover.com for review.

Best Practices

  • Don’t multithread client POST calls, this behavior can create system delays due to deadlocks.
  • Query with ‘modifiedTime’ filters when possible, in order to avoid re-polling unmodified data.
  • Minimize data usage. Merchants may be on limited mobile data plans.

Android

Best Practices

  • We strongly encourage developers to integrate some form of crash reporting utility into their Android products. This will help you maintain operational awareness of your product.
  • Developers are also encouraged to collect metrics about the usage of their app. This will help you build better products and increase awareness of any impacting issues.
  • To avoid confusing consumers, do not use the term PIN in your app.

Quality Code

Device Rotations

  • Clover Mobile and Clover Mini have display rotation disabled.
  • Clover Station uses display rotation when switching from employee facing mode to customer facing mode.
  • If your app will be available on Clover Station, it must gracefully handle display rotation.

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 AsyncTask’s background task.
  • Use a back-off switch when responding to errors, and confirm normal functioning before proceeding, instead of eagerly starting new loops.

Security

Web

Security

Merchant Data

  • The Clover API allows access to a database and should be dealt with the same security standards as database access.
  • Web applications should access the Clover API via server-to-server requests when possible.
  • Any data cached by your own services must be stored securely.

Limiting Client Access

  • Customer or employee facing apps must prevent unauthorized users from accessing privileged data, including the Clover credentials used by your app.
  • Use secure logins and session tracking if needed.
  • Server logic should prevent unauthorized access to data via injection.
  • Any data passed to the client in any format should be considered vulnerable.

Clover Integration

  • Make it easy for merchants to log in. The URL for your web app should launch the login flow, not navigate to the general home page for your business.
  • Include your Web URL prior to submission and test it with an example OAuth request.
  • Any app designed to be viewed or operated from a Clover device must be mobile-friendly.

Design

Image Assets

  • Launcher Icons should be mipmap resources.
  • Icons must conform to the standard android sizing (you can use third-party icon generators to resize your logo) :
    • 48 × 48 (mdpi) – Clover Station
    • 72 × 72 (hdpi) – Clover Mini/Mobile
    • 192 × 192 (xxxhdpi) – Clover Mini/Mobile first three apps

Graphic Design

  • Be aware of the screen dimensions of all the Clover devices you plan to support and design with these dimensions in mind.
  • A single merchant may have any or all of the Clover devices. Aim for a consistent user experience regardless of the device used.
  • If your app will include a customer facing component, your design will reflect on the business using your app. These interfaces should be pleasing and professional.

Usability

  • Your app will be used in fast paced working conditions. Strive for clear, easy to use, and robust workflows, with as few steps as possible.
  • Design should emphasize clarity, and accessibility – high contrast, readable fonts, large text and inputs.
  • If you are adapting an app that was developed for another platform, make sure that the app only includes features and buttons that are relevant to the Clover user.
  • Google Material Design Guidelines

Publishing

App Details

  • Your app details must include:
    • A clear, detailed description outlining its features and functionality
    • High resolution screenshots
    • Help/FAQ site URL
    • Support contact information for merchants
  • Improve your app’s visibility in the market by including descriptive keywords in the tagline.

App Pricing

  • Set your subscription(s) and be sure to enable and disable as needed.
  • Consider a freemium model to make your app attractive to download.
  • Metered, pay-per-action billing events, cannot be altered once your app is approved in the Clover App Market.  Once you implement metered events, you cannot add, delete, or modify this pricing tier.
  • Review the Billing section for more details.

App Submission

  • Be sure your app does not infringe on the intellectual property rights of others including the Clover brand, ex. do not use Clover or any other registered trademark in your app name to imply ownership or include the Clover brand in the root domain of your Help site.
  • The Clover App Market is live in US, UK, and Ireland.  When submitting to a new market, be aware of the differences between each country including local currency.
  • Developers must provide relevant login credentials and any other hardware or resources required to review your app.
  • If you have an Android app, you must submit both your app and your APK.  Once approved, be sure to publish both the app and the APK.