App Notifications

The app notification infrastructure allows you to send a message to either a single instance or all instances of an app running on a merchant’s devices.

NOTE

Our notification service is not guaranteed when or if it’ll be received by the device. If you require something more robust, you’ll need to implement your own or use an existing reliable message delivery service.

Sending a notification

Clover allows for two different types of notifications, app-level and device-level. Both notifications may only be received by your app, but device-level notifications are directed specifically to a single device. As usual, API requests need to be authorized with an access token.

The two POST endpoints are:

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

The POSTed JSON object has the following fields:

  1. event (string, required): 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. By default this is 5 days.
  3. data (string, optional): Payload of the notification. This is at most 4000 characters.

Please reference V3 Notifications.

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;
}

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. 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 either with a BroadcastReceiver or with Clover’s AppNotificationReceiver helper class.