Sending app notifications
Clover's app notification infrastructure allows you to send a message to a single instance of an app running on a merchant device, or to all of them.
NOTE
You can also implement your own or use an external message delivery service.
Sending a notification
Clover supports both app-level and device-level notifications. Device-level notifications are directed specifically to a single device.
The two POST
endpoints are:
Operation | Description |
---|---|
/v3/apps/{aId}/merchants/{mId}/notifications | Create a notification for an app |
/v3/apps/{aId}/devices/{deviceId}/notifications | Create a notification for a device. This endpoint requires the device ID. |
IMPORTANT
While making most Clover REST API calls, the
authorization: Bearer
header is set withauth_token
. For/v3/apps/
endpoints, you must replace theauth_token
with your app secret.You can find the app secret under App Settings on the Developer Dashboard.
curl --request POST \
--url https://apisandbox.dev.clover.com/v3/apps/{aId}/merchants/{mId}/notifications \
--header 'accept: application/json' \
--header 'authorization: Bearer {app_secret}'
--data '{"event":"test_notification","data":"New order created"}'
The JSON object in the payload has the following fields:
Parameter | Description |
---|---|
event (string, required) | The notification name specific to the app. This name uniquely identifies the notification. |
timeToLive (long, optional) | The time in seconds for which the notification lives. The notification disappears after the time expires. The default value is 5 days (432000 seconds). |
data (string, optional) | The payload for the notification. The maximum length is 4000 characters. |
See the Notifications section of the REST API reference for more information. You can find the merchant ID (mId
) and app ID (aId
) in the Installs and App Settings pages on the Developer Dashboard, respectively. The basic body of the notification is something like this:
{
"event": "test_notification",
"data": "New order created"
}
NOTE
An empty JSON response (
{}
) indicates that the message is queued for delivery.
Android example
protected Boolean doInBackground(Void... params) {
try {
// Your Notification model
final NotificationData notificationData = new NotificationData();
final CloverAuth.AuthResult authorization = CloverAuth.authenticate(context, CloverAccount.getAccount(context));
final GenericUrl uri = new GenericUrl(authorization.baseUrl +
"/v3/apps/" + authorization.appId +
"/merchants/" + authorization.merchantId +
"/notifications");
final String jsonString = JSON_FACTORY.toString(notificationData);
GenericJson json = new GenericJson();
json.set("data", jsonString);
json.set("event", NOTIFICATION_EVENT_NAME);
final HttpContent httpContent = new JsonHttpContent(JSON_FACTORY, json);
HttpHeaders headers = new HttpHeaders().setAuthorization("Bearer " + authorization.authToken);
HttpResponse httpResponse = HTTP_TRANSPORT.createRequestFactory()
.buildPostRequest(uri, httpContent)
.setHeaders(headers)
.execute();
return httpResponse.isSuccessStatusCode();
} catch (Exception e) {
Log.e(this.getClass().getSimpleName(), e.getMessage(), e.fillInStackTrace());
}
return null;
}
See the Push Notification Example Code for more information.
Receiving a notification
The Clover Service handles the POST
and pushes the message to the Clover Android Service running on each device that's currently online. The Clover Android Service processes the message and sends the following Intent to the app:
com.clover.sdk.app.intent.action.APP_NOTIFICATION
The app can handle the Intent with a BroadcastReceiver, or with Clover's AppNotificationReceiver helper class.
Updated 3 months ago