Use Web-Hooks to Track Events in IBM Cloud Push Notifications Service

Mobile

29 September 2018 4 min read

By:

Josephine Justin, Architect
Pradeep Gopalgowda, System Software Engineer

Web-hooks in the IBM Cloud Push Notification service

Have you ever wondered how events can be integrated into an IBM Cloud Push Notifications instance to gather custom analytics? How can the feedback be provided to those customers who are leaving or who have uninstalled the mobile apps?

The IBM Cloud Push Notifications service provides a mechanism to answer these questions and more. Web-hooks are user-defined callbacks that are triggered by an event in the instance.

IBM Cloud Push Notifications supports the following web-hook events:

onDeviceRegister
onDeviceUpdate
onDeviceUnregister
onSubscribe
onUnsubscribe
onNotificationStatusChange

Using IBM Cloud Push Notifications web-hooks

The following are a few of the possible uses of web-hooks:

onDeviceRegister is triggered when a device is registered for Push Notifications.
- Use these events to include the customer for custom targeted campaigns
- Use these for any billing-related integration
onDeviceUnregister is triggered when a device is unregistered for Push Notifications.
- Use these events to connect to your end customers using other channels since the customer has disabled Push.
onDeviceUpdate is triggered when a device is updated.
- Tracking the updated time of a device provides the details on when the customer last accessed the mobile app. If the customer doesn’t access the mobile app for a long time, you can send them a feedback form.
onNotificationStatusChange is triggered for every Push Notification.
- Use the FAILED status to track how many users have uninstalled the mobile app (i.e., when the failureReason is “Not Registered”). This helps you get the feedback from the end customer on why they uninstalled the mobile app.

Enabling monitoring using web-hooks

We’re going to explain the following steps involved in monitoring the events:

Deploy a web-hook receiver
Register an IBM Cloud Push Notifications instance with web-hooks
Monitor the web-hook receiver logs to understand the events
Events monitoring

Deploy a web-hook receiver

Use the following method to deploy an IBM Cloud node.js application that will receive the event details when posted by the IBM Push Notification service.

app.post(‘/receive’, function (req, res) {

latestWebhook = req.body;

console.log(req.body);

//invoke analytics / feedback / billing or any other backend system to use the details of the event

res.sendStatus(200);

});

This just receives and displays in the log. Any business logic can be attached to this method for further analysis or action.

Note: This doc assumes that the app is deployed at https://hookreceiver.mybluemix.net.

Register for a web-hook

Web-hooks can be registered using the Push Notifications Service REST APIs. To register a web-hook, use swagger, postman, or curl. Below is the POST to /webhooks which accepts the URL of the web-hook receiver and the event types. This means that the endpoint tracks all types of web-hooks. These can also be tied to specific event types, like onNotificationStatusChange.

The response of 200 OK indicates that the web-hook registration was successful.

Monitor the logs of the cf app

Since the web-hook receiver prints the posted JSON from the service, monitor the logs of the app, open a terminal, and issue the command “cf logs <appname>” to understand the events.

Note: This app just does logging when it receives the web-hook events. So, we are monitoring the logs but any business logic can be attached.

Register a device web-hook

When a device is registered, the web-hook is triggered. Since the web-hook registered with the service has the event types as “*”, it receives all types of events. The web-hook JSON posted to the receiver contains all the details of the registered device, including the time stamp and the platform.

Similarly, other events receive the corresponding JSONs.

Send notifications

For all notifications sent, there are various states maintained by the service.

SENT: Service has dispatched the notification to the cloud providers.
SEEN: Notification is received by the device.
OPEN: Notification is received by the device and clicked to open the mobile app.
INVALID: Device targeted for the notification is invalid. This can be because the device id /user id provided is not registered with the service or the app is uninstalled from the mobile device.

Success case

The following shows how to send a notification to a valid device using the dashboard (this can be done using the REST API too).

Once the notification is sent to a valid device, the event that is received is onNotificationStatusChange with the msgStatus as SENT. This contains a deviceIds attribute which is an array which lists all the devices the notification is sent to.

This contains a deviceIds attribute which is an array which lists all the devices the notification is sent to

When the notification is seen in the mobile app, the msgStatus will change to SEEN.

Failure case

When the mobile app is deleted from the device, the token becomes inactive and a failure feedback is triggered by the cloud provider. Any feedback from the cloud providers invokes an event in the Push Notification Service. When a notification is triggered to a device which has the app uninstalled, a FAILED web-hook is received with the appropriate failureReason.