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

Clover does not guarantee when or if a device will receive a notification through our service. If you require a more robust solution, you may either 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.

NOTE

Replace your Auth Token with the App Secret as the Authorization Bearer for this endpoint. You can find the App Secret in the Settings tab for your app in the Developer Dashboard.

The two POST endpoints are:

  1. App – /v3/apps/{aId}/merchants/{mId}/notifications
  2. Device – /v3/apps/{aId}/devices/{dId}/notifications

The JSON object in the payload has the following fields:

  1. event (string, required) – The app-specific name of the notification, useful as a key to allow for multiple types of notifications.
  2. timeToLive (long, optional): The time to live of the notification in seconds. The default is 5 days.
  3. data (string, optional): The payload for the notification. The maximum length is 4000 characters.

Please see the Notifications section of the REST API reference.
You will need to fill out the API Token and mId on top of the page with the app’s App Secret (not API Token) and merchant’s mId.

The basic body of the notification is something like this:

{
  "event": "test_notification",
  "data": "Up to 4k of data"
}

Sample Android Code

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.