Sending notifcations

Sending a notification

Send a POST request to https://pushitgood.eu/v1/notify with the following payload, encoded as a JWT signed with your APIKEY. A sample Python implementation looks like this:

import requests

data = {
    "client_id": CLIENT_ID,
    "uid": "555",
    "title": "Notification title"
    "body": "Notification content"
    "url": "URL to open when notification is clicked"
    "tags": ["tags", "to", "target"],
    "actions": [
        {
            "action": "custom-action",
            "title": "Custom action",
            "icon": "https://site.example/action.png"
        }
    ],
    "timeout": 3600,
    "webhook": "https://site.example/pushitgood-webhook",
}
requests.post(
    "https://pushitgood.eu/v1/notify",
    jwt.encode(data, key=APIKEY, algorithm="HS256")
)

# Result of the notification, see below for explanation
result = requests.json()

You can also send the payload as a JSON payload, with the APIKEY specified in an authorization header, for example:

$ curl \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $APIKEY" \
    --request POST \
    --data '{"uid":"555","title":"Notification title", ... }' \
https://pushitgood.eu/v1/notify

If uid is specified, a notification will be sent only to the user with that uid.

If tags is specified, notifications will be sent to any user that has one or more of the listed tags.

If neither is specified, no notifications will be sent

If timeout is specified, this is the time in seconds that pushitgood will wait for a confirmation that the notification has been received before updating the notification’s state to timeout and calling your webhook.

The notify endpoint will send notifications to each device subscribed for the specified user(s), and return a JSON data structure in the following format:

{
    // Unique identifier for the notification
    "nid": "...",

    // Each notification fans out to multiple Push API
    // requests, one per subscribed device.
    "pushes": [
        {
            // Identifier for this push
            "pid": "...",

            // user the push was sent to
            "uid": "...",

            // subscription the push was sent to
            "sid": "...",
        },
        ...
    ]
}

Custom actions

The notifications API allows you to define custom actions to be displayed under the notification body.

Note: notification actions are only available in Chrome and Edge. Browser may also limit how many actions are displayed.

Use the actions property of the notify api payload to define notification actions:

data = {
    ...
    "actions": [
        {
            "action": "custom-action",
            "title": "Custom action",
            "icon": "https://site.example/action.png"
        }
    ],
}

The action property is used by javascript code to identify the selected action. The title and icon properties define the text and image used for the button that the user clicks on,

The default pushitgood event listener does not handle custom actions, so to use notification actions you must supply your own. Amend your /worker.js script as follows:

importScripts("https://pushitgood.eu/v1/worker.js");

// Remove pushitgood's default event listener
self.removeDefaultNotificationClickListener();

// Register an event listener to handle your site's custom actions
self.addEventListener(
    "notificationclick",
    (event) => {
        event.notification.close();

        switch (event.action) {

            // Replace this with your custom action name.
            // Edit the openWindow call to include the url to load
            case "custom-action":
                event.waitUntil(self.openWindow(...));
                break;

            // If you have multiple custom actions,
            // add more cases as necessary
            case "custom-action-2":
                event.waitUntil(self.openWindow(...));
                break;

            // The default case will be used if the user does not
            // select an action, or if the browser does not support
            // notification actions
            default:
                event.waitUntil(self.openWindow(event.notification.data.url));
        }
    }
);