What's NewAnnouncementsWebinarsCommunityBlog

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:

OperationDescription
/v3/apps/{aId}/merchants/{mId}/notificationsCreate a notification for an app
/v3/apps/{aId}/devices/{deviceId}/notificationsCreate 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 with auth_token. For /v3/apps/ endpoints, you must replace the auth_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:

ParameterDescription
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