Setting up notifications

During the onboarding process the end-user can indicate which notification channels should be used for triggering notifications that are available in the NET2GRID Insight Platform instance.

There are 2 layers by which permissions for notifications are managed:

1. The notification channel being enabled
2. The topic applicable for this category of notification is not muted for the channel

Below is a screenshot of how notifications setup is defined in the Ynni app on end-user settings

In this section, the following processes will also be described.

1. Enabling/Disabling notifications of a specific channel as per end-user request
2. Managing notification topics permissions
3. Managing inbox notifications through the app
4. How to test a notification during development

Enabling a notification channel

As mentioned in the introduction, notification channels are the different media types through which notifications can be delivered. The Insight currently supports the following channels:

• email: notifications will be delivered to the email address of the end user. They are configured per end-user account.
• push: notifications will be delivered as a mobile push notification to the end-user. They are configured per mobile device and application in an end-user account.
• inbox: notifications will be delivered to an in-app inbox. They are configured per end-user account.
• REST API: notifications are being sent directly to the customer's or Label partner's REST API. More information can be found here

All notification channels (except for inbox notifications) are disabled by default for every user in NET2GRID Insight platform. To start receiving notifications on a channel the end user will have to give their consent.

📘

Inbox notifications are enabled by default without the user's consent and cannot be disabled. Inbox notifications are not delivered actively to the end user, instead the application is responsible for fetching them from the CE API and displaying the notifications inside the application.

For more details about integrating inbox notifications have a look at the Managing inbox notifications section.

To allow end users to give their consent and start receiving notifications on a certain channel the CE API provides the following endpoint:

PUT /v2/notification/channel/enable
Authorization: Bearer <access_token>

This call need to be performed for every channel the end user would like to receive notifications on. The full description of the endpoint can be found here.

For instance, when the end-user wants email notifications to be enabled the request body will look like:

{
    "channel": "EMAIL"
}

While when the end-user wants push notifications to be enabled in their device, the call from the app to the CE API should contain the following information:

{
     "channel": "MOBILE_PUSH",
     "device_type": "ANDROID",
     "device_token": "<deviceToken>",
     "device_id": "<deviceId>",
     "app_identifier": "<app_identifier>"
}

📘

Push notifications can be enabled for multiple devices on the same account.

To do so a request to the Enable notification channel should be made on each individual device.

🚧

Requirements from the app for push notifications

For push notifications to work, NET2GRID Insight Platform needs to be setup first for every app that is going to be able to trigger push notifications.

The following information is required from the app developers to setup push notifications for each app:

1. Google API key for Android applications
2. TLS certificate for iOS applications. The certificate needs to be in .p12 format and the private key needs to be provided (if setup)

Once the setup is complete, NET2GRID will provide to the customer the app_identifier that can be used to trigger notifications in the relevant app.

📘

Support for multiple apps in a single Insight instance

NET2GRID supports multiple applications that can be used to receive notifications. This is useful for sandbox applications that can be used separately to test the app prior to releasing the app.

The app_identifier field in the Enable notification channel endpoint identifies this specific app.

Disabling a notification channel

Similar to enabling notification channels, it's also good practice to allow end users to unsubscribe from receiving notifications on a certain channel. To accomplish this that CE API provides the Disable notification channel endpoint.

PUT /v2/notification/channel/disable
Authorization: Bearer <access_token>

The request body will be the following when email notifications should be disabled:

{
    "channel": "EMAIL"
}

while when push notifications should be disabled it should look like:

{
     "channel": "MOBILE_PUSH",
     "device_id": "<deviceId>"
}

📘

Push notifications are disabled on a device level

If push notifications are enabled on multiple devices for this account, only the push notifications for this device will be disabled. The other devices will continue to receive notifications until the push notification channel is disabled on those devices as well.

Get current notification channel state

To verify if a particular notification channel is enabled or disabled for the current user the CE API provides the Check Channel Status endpoint:

GET /v2/notification/channel/status/{channel}?device_id={device_id}
Authorization: Bearer <access_token>

The device_id is an optional query parameter that should be used only in case of checking the push notification configuration that is device specific.

A successful call to this endpoint will result in a response similar to:

{
  "status": "ok",
  "data": {
    "enabled": true,
    "mutedTopics": [
      "HYPERACTIVE_ALARM"
    ]
  }
}

The enabled parameter indicates if the notification channel is enabled or not. The mutedTopics parameter contains an array of topics the user muted. Topics are explained in detail in the Topics page.