Getting started with Pushnoti

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)

Pushnoti SDK

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:

Copy to Clipboard

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

Copy to Clipboard

If the client’s service worker options customization is required then clientsite.js should contain the following code:

Copy to Clipboard

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:

Copy to Clipboard

The message is a JavaScript object and has the following properties:

Copy to Clipboard

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

Copy to Clipboard

const tryToRegisterVisitor = async () => {
  const permissions = await window.PushnotiSDK.initFunction()
  if (!permissions) {
    // service worker registration fault
    return
  }

if (permissions.isDenied) {
    // visitor denied subscription already
    return
  }

if (permissions.shouldOptIn) { // the default setting in the browsers (normally, if not modified by user)
    // visitor should opt-in
    // display something (e.g. a button) that will require human interaction and, after the click will
    // invoke window.PushnotiSDK.optInCallback, which returns true if the visitor has accepted subscription
    // see how to use the Pushnoti widget below
    return
  }

// visitor has granted permissions already.
}

const makeRegistration = () => {
  if (!window.PushnotiSDK || typeof window.PushnotiSDK.initFunction !== 'function') {
    // SHOULD wait for PushnotiSDK
    setTimeout(function () {
      makeRegistration()
    }, 200)
    return
  }
  tryToRegisterVisitor().then().catch()
}

window.customPushnotiReceiver = async message => { // async is not mandatory
  console.log('Message from Pushnoti SDK', message)
}

/**
 * All should start in the loaded document
 */
if (document.readyState === 'loading') {
  document.addEventListener(
    'DOMContentLoaded',
    event => {
      setTimeout(function () { // to leave event handler context, or browser may complain on too long callback
        makeRegistration()
      }, 200)
    },
    false,
  )
} else {
  makeRegistration()
}

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:

Copy to Clipboard

The ‘tryToRegisterVisitor’ function (see the Client front side scripts section above) should be modified:

Copy to Clipboard

The following code should be added:

Copy to Clipboard

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:

Copy to Clipboard

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:

Copy to Clipboard

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)

Copy to Clipboard

custom click processing (the body of the function is just an example)

Copy to Clipboard

Getting started with Pushnoti

Pushnoti SDK

Pushnoti service worker core

Client front side scripts

Pushnoti subscribe widget

Client service worker

Share This Article