The following components are required for the site integration
- Pushnoti SDK
- Pushnoti serviceworker core
- Pushnoti subscribe widget (optional)
- Client front side scripts
- Client service worker
The API Documents can be found here. (user/pass = developer/developer)
The SDK implements the push subscription protocol as it is defined by the browsers and W3 specifications:
- Checks if the push notifications are supported by the browser
- Initializes and sanitizes the service worker options (path and scope)
- Check the current state of the notifications permissions (as set by the user)
- Provides callback for the subscription opt-in widget
- Registers the service worker
The SDK should be included by a script tag in thesection of the HTML document:
These data should not be changed by the frontend scripts. Use the customization functions as described in the
Client front side scripts section below.
The frontend scrips should wait until the ‘window.PushnotiSDK’ structure has been completed. See the sample code below.
Pushnoti service worker core
The core service worker implements all required functionality:
- Initialises and maintains the push subscription
- Receives and displays the push notifications (can be customized)
- Communicates with Pushnoti service backend (reports new subscriptions and clicks on the notifications)
- Opens (on a click event, can be customized) URLs if there are some in the notification (see the notification data description)
- Provides customization (see the client’s service worker description below)
The core script is provided to the clients as a single JS file. The file is available for the download from the Pushnoti Dashboard.
Client front side scripts
The client front side scripts are implemented by the client.
The scripts are responsible for the proper initialization and synchronization of the components.
The example below assumes that the frontend scripts are included in the section as ‘/scripts/clientsite.js’:
If the client’s service worker options customization is required then clientsite.js should contain the following code:
The core service worker can communicate with the frontend scripts using Pushnoti SDK functionality.
The messages are sent only if the visitor is online (is browsing the site)!
The message delivery depends on many circumstances and is a “best effort” service.
The messages can be received by the client’s script if the following function is defined:
The ‘type’ is the ‘meaning’ of the message and can be one of:
– ‘subscribed’ – new subscription. ‘clickedOn’ and ‘notificationId’ are both ‘null’
– ‘unsubscribed’ – cancelled subscription.
– ‘subscriptionfault’ – attempt to subscribe was unsuccessful. All properties are null.
– ‘subscriptionexists’ – the visitor has been subscribed already. ‘clickedOn’ and ‘notificationId’ are both ‘null’
– ‘click’ – the visitor clicked on the notification. ‘clickedOn’ is URL contained in the notification (primary URL, or action URL)
– ‘close’ – the visitor just closed the notification without the click.
– ‘push’ – the visitor has received the notification.
Please note that messages of ‘unsubscribed’, ‘subscriptionfault’, and ‘subscriptionexists’ are the most
unreliable because there are many ways to unsubscribe, as well as many ways to fail the subscription process.
The `subscriptionexists` message may not be received because of asynchronous nature of the service
worker: the event may raise before Pushnoti SDK has established the communication.
The ‘notificationId’ is the same as can be seen on the Pushnoti Dashboard, and
‘subscriberId’ can be used in the ‘sendTo’ field in the ‘Notification Delivery’ API of Pushnoti.
The sample of the registration functionality implementation (the most of the ‘clientsite.js’):
See how to process the opt-in using the Pushnoti widget (implemented as a custom component) below.
Pushnoti subscribe widget
The widget should be included in the <head> section:
The ‘tryToRegisterVisitor’ function (see the Client front side scripts section above) should be modified:
The following code should be added:
The widget provides some interactive elements, which prompt the visitor to accept or decline the subscription.
After the visitor has clicked on one with the meaning ‘yes’ the widget runs subscription callback and removes itself.
Otherwise, the widget just removes itself from the screen.
Note that the widget provides just the first opt-in. After the visitor has agreed on the proposal the browser displays its own
dialog where the visitor has to make the second decision on accept or decline the subscription.
Such double opt-in procedure with real (made by human) interaction (click) is strongly recommended by W3 specifications and is mandatory in some browsers.
The widget can be customized.
Client service worker
The client service worker is implemented by the customer.
It is required by the W3 specification: the service worker must be provided by the client’s site.
The client’s service worker also provides important information for the core service worker: client and application (site) IDs.
In the common case the code is rather simple:
where CLIENT_ID and APP_ID are provided by the Pushnoti Dashboard after a client has completed the registration procedure.
The ‘SW_CORE_URL’ supposed to be URL of Pushnoti CDN ‘https://pushnoti.ams3.cdn.digitaloceanspaces.com/sw/service-worker-core.js’.
Unfortunately, the recent versions of FireFox browser forced the same origin policy to this URL (not in line with the spec).
Because of this, the ‘SW_CORE_URL’ should be the same as for the client service worker (the site root usually).
We provide the clients with the core service worker script, which may be stored in the same directory with the client’s service worker.
Optionally, the entire core service worker script can be copied and pasted into the client’s service worker replacing ‘importScripts(SW_CORE_URL)’
The client’s site routing should be properly configured to deliver the file(s) on request.
The scheme must be https:// for both client’s and core service workers.
The simples way is to deliver the service worker from the site root and name it service-worker.js.
Thus, the client’s service worker URL can be https://client.site.tld/service-worker.js.
The core script name and path do not matter and can be any.
If minimal security is necessary, one can check that the service worker request has Service-Worker: script header, which means that
the request is from a browser (or, from a person with minimal knowledge of the subject at least).
Note: the request initiated by the ‘importScripts’ does not include this header.
If the delivery from the root URL cannot be implemented, more tuning is required.
The client’s frontend scripts should implement the following function:
Finally, the response to the service worker request must include Service-Worker-Allowed: <the same scope as in the options above> header.
The client’s service worker can implement any events processing functions and any additional functionality if necessary.
The core service worker invokes the following functions if they are implemented in the client’s service worker:
custom display of the push message (the body of the function is just an example)
custom click processing (the body of the function is just an example)