Integration guide

This guide covers installing the javascript and the endpoints your application needs to provide in order to subscribe users to push notifications through Pushitgood.

Before starting make sure you have a pushitgood.eu client_id and apikey. The apikey must be kept secret and must never appear in client side code.

What your application must provide

The service worker

Add a javascript file in the root directory of your website called /worker.js, containing the following line:

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

If you already have a file called /worker.js you can use another name, but be sure to amend the calls to registerServiceWorker in the later JS code snippets.

The user-details endpoint

The user-details endpoint returns your client_id and information about the user currently being subscribed, formatted as a HS256-signed Javascript Web Token (JWT). A sample Python implementation looks like this:

def user_details(request):
    return Response(
        jwt.encode(
            {
                "client_id": "my client id",
                "uid": "user identifier as a str",
                "tags": ["list", "of", "tags"],
                "device_name": "unique_device_name",
                "webhook": "https://site.example/pushitgood-webhook",
            },
            key=APIKEY,
            algorithm="HS256"
        )
    )

The payload is as follows:

  • client_id: (string) your pushitgood client id

  • uid: (string) uniquely identifies the user.

  • tags: (list of strings, optional) arbitrary tags that you can use to target a notification to a group of users. Tags are associated with the user, not the subscription.

  • device_name: (string, optional) a identifier for the device being subscribed. This can be an arbitrary string chosen by you to represent the user’s device (eg ‘desktop’ or ‘phone’), or left unspecified. Only one subscription per named device is allowed. If the user subscribes a second time with the same device_name, the previous subscription is deleted.

  • webhook: (string, optional) webhook endpoint url

Javascript snippet for subscribing users

Non-interactive version

The following JS snippet subscribes the user automatically and silently on page load. Edit the script to provide your the user-details endpoint path in the call to subscribeUser.

<script type="module">
    import * as pig from "https://pushitgood.eu/v1/static/susbcribe.js";

    pig.registerServiceWorker("/worker.js");

    // Automatically subscribe the user, requesting permission as required
    pig.getSubscription().then(
        (subscription) {
            if (subscription === null) {
                pig.subscribeUser("/path/to/user-details-endpoint.json");
            }
        }
    }
</script>

Interactive version

The following JS snippet displays a subscribe / unsubscribe button, and requires positive user interaction before the user is subscribed. Edit the script to provide your the user-details endpoint path in the call to subscribeUser.

<div id="ButtonContainer"></div>

<script type="module">
    import * as pig from "https://pushitgood.eu/v1/static/subscribe.js";
    pig.registerServiceWorker("/worker.js");
    let button = document.createElement("button");
    document.getElementById("ButtonContainer").append(button);
    button.addEventListener(
        "click",
        (event) => {
            if (event.target.name == "subscribe") {
                pig.subscribeUser("/path/to/user-details-endpoint");
            } else {
                pig.unsubscribeUser("/path/to/user-details-endpoint");
            }
        }
    );
    pig.registerSubscriptionCallback(
        (subscriptionResponse) => {
            button.innerHTML = (subscriptionResponse.subscription) ? "Stop notifications!" : "Get notifications!";
            button.name = (subscriptionResponse.subscription) ? "unsubscribe" : "subscribe";
        }
    )
</script>

registerSubscriptionCallback and handling failed subscriptions

The function pig.registerSubscriptionCallback registers a function to be called:

  • When the service worker is registered (typically on page load)

  • Whenever pig.subscribeUser is called

  • Whenever pig.unsubscribeUser is called

The function will be called with an object containing the following keys:

subscription

The PushSubscription object, or null if the user is not subscribed

action

One of 'subscribe', 'unsubscribe', or 'register_serviceworker'

result

For subscribe actions, this will be one of 'granted' or denied, reflecting the user’s browser notification permission. For other actions this is true.

If a user has denied the notification permission in their browser settings, subscription requests will fail silently – the browser does not give any indication that the subscription request was denied and does not prompt the user to grant the notification permission.

In this case you may want to use a subscription callback to display a suitable message:

pig.registerSubscriptionCallback(
    (subscriptionResponse) => {
        if (subscriptionResponse.action === "subscribe" && subscriptionResponse.result != "granted") {
            alert("Please enable notifications for this site before trying again");
        }
    }
)