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 :ref:`service worker script <ServiceWorker>`, hosted at the top level directory of your site
- A :ref:`user-details endpoint <UserDetails>`
- The :ref:`javascript snippet <Snippet>`, embedded
  on the page(s) where you want users to subscribe to notifications.

.. _ServiceWorker:

The service worker
------------------

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

.. code:: javascript

    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.

.. _UserDetails:

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:

.. code:: python

    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


.. _Snippet:

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``.

.. code:: html

    <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``.

.. code:: html


    <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:

.. code:: javascript

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

.. _PushSubscription: https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription