Overview

Using a Custom Activity allows you to take complete control of the screen and user interaction on a Clover device to launch an Android activity that you have created. With Custom Activities, you have greater control over the user's experience on the device, such as replacing default Clover displays with customized displays or adding displays to collect customer data.

On the Clover platform, Custom Activities are built and deployed as apps, which are privately pushed to your merchants. Merchants will not be able to download these apps from the Clover App Market. Once the Custom Activity is pushed to a merchant using your integration, you can initiate the activity to appear on the targeted device through the REST Pay Display API.

Learn more about Android Activities.

Custom Activity types

There are two types of Custom Activities:

• Blocking activity—Ties the activity life cycle to the life cycle of the initiating request. The initial request launches the activity, and a response returns after the activity ends. This is usually the result of user input, but it can also occur because of a cancel, device reset, or request timeout. Blocking activities are ideal to collect user input—for example, user acceptance of a waiver, loyalty information, tip amount, and so on.

• Non-blocking activity—Decouples the life cycle of the activity from the request. The request launches the activity and immediately returns a response to the user. A non-blocking activity continues to run or display until another foreground device request is made—for example, a screen activity or the device receives a cancel or device reset command. While the immediate response prevents the activity from collecting data from the response, it is well suited for a variety of display functions, such as displaying a custom-branded logo, or looping pictures/video while the device is in an idle state.

📘

NOTE

A property in the initiating request determines if an activity is blocking or non-blocking.

Clover example APK

Clover provides an example Custom Activity Android Package Kit (APK) that includes basic examples of blocking and non-blocking activities.

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is running REST Pay Display and is in an idle state, that is, no payment is being taken.
• Request includes the required headers.

Steps

Development steps

• Build a Custom Activity Android APK or use our example for testing in Sandbox.
• Custom Activity is pushed to the merchant as a private app.
  • In Clover sandbox environment, this is done by side-loading the APK.
  • In Clovet production environment, this is done by coordinating with Developer Relations.

Launch activity steps

After the prerequisites are met, you can launch your Custom Activity:

1. Send a POST request to /v1/device/custom/activity endpoint.
   • Action field in the request is required and must match the activity's intent-filter action name from the Android manifest.
   • Use the Payload property to pass data elements to your custom activity.

Custom Activity request and response fields

See the v1 connect.yaml file schemas for request and response descriptions.

Custom Activity examples

Blocking activity example

Request

curl --location --request POST 'https://YOUR_DEVICE_IP:12346/connect/v1/device/custom/activity' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Clover-Device-Id: YOUR_DEVICE_SN' \
--header 'X-POS-Id: My POS ID' \
--data-raw '{
"action": "com.clover.cfp.examples.BasicExample",
    "block": true,
    "payload": "My payload data"
}
'

Response

Activity finishes, the device returns to the default idle state—that is, the spinner screen appears—and the following HTTP response appears:

Response Code: 200

{
  "payload": "{\"value\":{\"click\":\"Finish!\"}, \"rejected\":false}"
}

Non-blocking activity example

Request

curl --location --request POST 'https://YOUR_DEVICE_IP:12346/connect/v1/device/custom/activity' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Clover-Device-Id: YOUR_DEVICE_SN' \
--header 'X-POS-Id: My POS ID' \
--data-raw '{
"action": "com.clover.cfp.examples.CarouselExample",
  "block": false
}
'

Response

The response returns automatically:

Response Code: 200

{}

Error examples

Request is missing the required Action field

Response Code: 400

{
  "code": "processing_error",
  "message": "Action is null!",
  "requestId": "1b2b0669-8b42-4188-8bbc-7fd69222f959",
  "requestType": "CUSTOM_ACTIVITY",
  "type": "api_error"
}

Request contains an incorrect Action field or the Custom Activity is not installed on the device

Response Code: 400

{
  "code": "processing_error",
  "message": "Custom Activity 'INVALID_ACTIVITY_ACTION' not found. Make sure the app containing the Custom Activity is installed on this device.",
  "requestId": "eff99d4c-b0c6-4b1d-a681-ad4edc886ce8",
  "requestType": "CUSTOM_ACTIVITY",
  "type": "api_error"
}

The following message appears on the device: