The right way to Use a PHP Push Notifications Class on Your Net Web site in 2023 with this Ship Net Push Notifications Tutorial – PHP Net Push Notifications Server package deal weblog

1.1. A quick view on net push notifications

Net push notifications enable messages to be despatched on to customers, even when they don’t seem to be presently visiting the sender’s website web page.

Presents, information or different related data might be despatched at any time and customers might be redirected to a desired URL. From the consumer’s perspective, push notifications have the benefit that your entire subscription course of is nameless (the supplier doesn’t want names or contact particulars similar to an e mail deal with or different data) and the service might be terminated at any time.

To ensure that a supplier to be allowed to ship push notifications to a consumer, the consumer should first explicitly take any motion on the sender’s website to substantiate that he needs to obtain these messages.

As well as, a unsubscribe choice is routinely built-in in every delivered push message (how and the place this unsubscribe choice is obtainable is determined by the customers working system and/or browser).

The push notifications aren’t displayed inside the website space of a browser, however both in a separate popup window or through a service supplied by the working system (this varies relying on the machine, working system and browser and a few browsers enable marginally settings – see additionally within the appendix).

A notification often consists of a title, a brief textual content (optionally with an icon and/or an image) and often accommodates a direct hyperlink to the website it pertains to.

The notification system is a particularly highly effective medium for interacting with customers. Nevertheless, the supplier ought to at all times take care to not publish an excessive amount of on this medium, in any other case customers will deactivate all notifications.

1.2. How net push notifications works

An exterior push service is linked between the browser at consumer facet and the message supplier’s server. The push service is accountable for delivering messages from the server to the respective customers.

When requesting details about the subscription from the online push API, the general public a part of a key have to be handed. With the assistance of the non-public a part of this key, the server in flip has to encrypt the messages earlier than sending them.

1.2.1. The subscription course of

Code for 2 duties have to be built-in in your website web page. The primary is to provide the customer the chance to subscribe to the online push notifications. As well as, the location web page should set up a service (‘service-worker’), with which the consumer is registered on the server and acquired messages are processed. The service-worker is downloaded within the background to the consumer platform in order that it may be executed exterior of the context of the location web page.

If the consumer subscribes to the service, the service-worker is registered (1). The service-worker in flip requests all required data by means of the online push API (2) and sends this through an HTTP request (3) to the server. The server shops this data in his database (4) in order that notifications might be despatched to the consumer.

1.2.2. Sending notifications

Notifications can now be despatched from the server to all registered subscriptions with a HTTP request (2). As a way to appropriately determine your self, a signature have to be transmitted within the request header. This signature is generated from the general public key used for registration along with the non-public a part of the important thing (1). The precise message and presumably additional data are transmitted as consumer information – additionally encrypted. If the formatting and encryption are appropriate and the signature validated, the push service sends the notification to the consumer (3).

1.2.3. The required key pair (VAPID)

A key pair containing a public and a non-public key’s required for the entire course of. These two keys are referred to as VAPID keys (VAPID: Voluntary Software Server Identification for Net Push; RFC 8292 – https://instruments.ietf.org/html/rfc8292) and should be generated as soon as for a website.

There are numerous instruments obtainable for making a VAPID key pair. Alternatively, on-line a key pair might be generated e.g. at https://instruments.reactpwa.com/vapid. The non-public key ought to by no means be seen to the tip consumer (e.g. in a JS script or someplace else), however ought to solely be used on the server for encryption when creating notifications. VAPID safety ensures that notifications can solely be despatched to purchasers from the licensed server.

Very detailed details about VAPID might be discovered within the following weblog put up:
https://weblog.mozilla.org/companies/2016/04/04/using-vapid-with-webpush/

2. Implementation

After the final consideration within the earlier chapter, we now flip to the precise programming.

2.1. The subscription on the consumer facet utilizing JavaScript and  a HTML5 Push Notification Instance

Because the consumer facet runs within the net browser, all the things on the consumer is applied in JavaScript. Notice that the combination of the features inside the UI of the website isn’t a part of this tutorial!

Some features in reference to the online push API are processed asynchronously, which is why the promise sample is used a number of occasions within the following code. Quite a few articles on this matter might be discovered on the web – at https://net.dev/guarantees/ rookies can discover an excellent clarification.

2.1.1. Verify whether or not HTML push notifications can be found

To begin with, it have to be checked whether or not all necessities are met so as to have the ability to obtain push notifications on the present browser. To do that, the browser should help the online push API and the Website online should run in a safe context (HTTPS).

For more information concerning the API and the supply within the present browsers see https://www.w3.org/TR/push-api/ and https://caniuse.com/#feat=push-api.

perform pnAvailable() {
var bAvailable = false;
if (window.isSecureContext) {
// operating in safe context - verify for obtainable Push-API
bAvailable = (('serviceWorker' in navigator) && 
('PushManager' in window) && 
('Notification' in window)); 
} else {
console.log('website should run in safe context!');
}
return bAvailable;
}

2.1.2. Receive permission to ship a HTML push notification to the consumer

Because of the misuse of push notifications up to now, consent to show notifications ought to solely be requested after the consumer has intentionally acted on it (e.g. by clicking a button – not routinely when the web page hundreds!).

The next perform ought to subsequently finest be built-in by yourself Website online utilizing a hyperlink or button in a separate space with corresponding explanations for the push notifications. This needs to be seen as a rule and never simply as ‘finest observe’.

As a supplier, it needs to be borne in thoughts that many (… most) customers usually tend to reject an early request with out detailed explanations. And as soon as the request has been rejected, it’s tough to get the consumer again on board later.

If the consumer has already rejected the show of notifications, he ought to now not be bothered with additional data concerning the subscription to the push notifications, since he should first deactivate the blocking of the notifications through the respective browser perform! If crucial, this may be defined in additional element at an appropriate level (e.g. below FAQ’s).

async perform pnSubscribe() {
    if (pnAvailable()) {
        // if not granted or denied up to now...
        if (window.Notification.permission === 'default') {
            await window.Notification.requestPermission();
        }
        if (Notification.permission === 'granted') {
            // register service employee
            await pnRegisterSW();
        }
    }
}

The browser remembers the consumer’s final choice. This may be decided at any time through the notification.permission property. If the consumer has not but decided, this property is about to ‘default’, in any other case to ‘denied’ or ‘granted’. With most browsers, the choice might be reset by the consumer within the title bar or within the web page settings.

2.1.3. Registration of the service-worker

As a way to obtain and show push notifications, even when the consumer isn’t on that website web page, a service have to be registered operating within the background exterior the context of the web site and is subsequently at all times prepared to answer notifications.

The so referred to as service-worker is a separate javascript file that the browser copies from the origin location on the net to the native laptop and executed there.

async perform pnRegisterSW() {
    navigator.serviceWorker.register('PNServiceWorker.js')
        .then((swReg) => {
            // registration labored
            console.log('Registration succeeded. Scope is ' + swReg.scope);
        }).catch((e) => {
            // registration failed
            console.log('Registration failed with ' + e);
        });
}

It’s not essential to verify whether or not the service-worker has already been registered. The browser (… the online push API) takes care of it. After registration, all the things inside the context of the web site is completed. All additional steps are carried out inside the service-worker.

All required features and a few helpers whereas testing included in PNClient.js.

2.1.4. Implementation of the service-worker

Within the context of our website web page, we’ve got registered the service-worker up to now and are actually devoted to his duties. When registering, the required javascript file was downloaded and executed. The registration succeeds provided that the script might be executed with out errors.

The one code within the service employee that’s executed instantly is to register listeners for a number of occasions:

// add occasion listener to subscribe and ship subscription to server
self.addEventListener('activate', pnSubscribe);
// and take heed to incomming push notifications
self.addEventListener('push', pnPopupNotification);
// ... and take heed to the press
self.addEventListener('notificationclick', pnNotificationClick);

2.1.4.1. Subscribe to push notifications and ship subscription to the server

Within the listener of the ‘activate’ occasion, the notification is subscribed utilizing the online push API. The general public VAPID key (see 1.2.3.) is required for this. As well as, the perform requires the boolean worth ‘userVisibleOnly’ as parameter, which should at all times be set to true.

Touch upon this parameter
When designing the online push API, there was a consideration if this parameter can be utilized to regulate whether or not a message typically needs to be exhibited to the consumer or whether or not sure actions can solely be carried out within the background.

Nevertheless, there have been issues that this is able to create the likelihood for builders to carry out undesirable actions with out the consumer’s data. This parameter can subsequently be considered a ‘silent settlement’ that the consumer at all times get a message when a push notification arrives.

async perform pnSubscribe(occasion) {
    console.log('Serviceworker: activate occasion');
    attempt {
        var appPublicKey = encodeToUint8Array(strAppPublicKey);
        var choose = {
                applicationServerKey: appPublicKey, 
                userVisibleOnly: true
            };
        
        self.registration.pushManager.subscribe(choose)
            .then((sub) => {
                // subscription succeeded - ship to server
                pnSaveSubscription(sub)
                    .then((response) => {
                        console.log(response);
                    }).catch ((e) => {
                        // registration failed
                        console.log('SaveSubscription failed with: ' + e);
                    });
            }, ).catch ((e) => {
                // registration failed
                console.log('Subscription failed with: ' + e);
            });
        
    } catch (e) {
        console.log('Error subscribing notifications: ' + e);
    }
}

The general public VAPID key have to be transferred to the push supervisor as a UInt8 array. If profitable, the push supervisor returns a subscription object. This object accommodates all data the server wants along with its personal VAPID keys to have the ability to encrypt and ship push notifications to this consumer. For this goal, the knowledge acquired have to be despatched to the server.

The information is shipped to the server as JSON-formatted textual content within the physique of a POST HTTP request. For transmission, we use the fetch() methodology of the javascript Fetch API. This methodology permits sources simply to be accessed or despatched asynchronously over the community.

async perform pnSaveSubscription(sub) {
    // stringify object to put up as physique with HTTP-request
    var fetchdata = {
            methodology: 'put up',
            headers: { 'Content material-Sort': 'software/json' },
            physique: JSON.stringify(sub),
          };
    // we're utilizing fetch() to put up the information to the server
    var response = await fetch(strSubscriberURL, fetchdata);
    return response.json();
}

The goal ‘strSubscriberURL’ is a service that needs to be supplied in your server. It accepts the transmitted information and shops it in a database. The implementation of this service is described in part 2.2.

If extra particular data is required along with the present subscription (e.g. login information of the consumer, a reference to a particular order or reservation, …), this also needs to be transferred right here, since that is the one direct hyperlink between consumer and server.

2.1.4.2. Displaying the acquired PUSH notifications

In distinction to the server facet, on the consumer facet the online push API (and the push companies) takes over all duties concerning verification and decryption, which allows us to focus on the show of the notification.

When a push notification arrives, a corresponding ‘push’ occasion is triggered to the service employee. So the very first thing to do is to arrange a listener to this occasion. All related data is handed to the listener within the ‘occasion’ parameter.

Along with some inside properties, this object primarily accommodates the information despatched by the server. The format through which the information is transmitted is the only real duty of the sender. At this level, pure textual content is assumed – this may occasionally additionally might be despatched for check functions from some instruments or from some browsers developer instruments. (See appendix).

After we’ve got applied the sending of the notifications in chapter 2.3. we are going to swap to an object encoded as a JSON string. By means of this object we’re capable of management a lot of the properties of the notification to be displayed. To begin with, it is nearly displaying a easy textual content message.

perform pnPushNotification(occasion) {
    console.log('push occasion: ' + occasion);
    var strTitle = 'Notification';
    var strText = 'empty Notification acquired!';
    if (occasion.information) {
        strText = occasion.information.textual content();
    }
    var promise = self.registration.showNotification(strTitle, choose);
    occasion.waitUntil(promise);
}

To show the message the showNotification() perform have for use, which is handed the title and an choice object. This selection object can include properties to regulate the content material, format and habits of the notification.

A extra detailed description follows in Chapter 2.3 when notifications are despatched from the server. The ultimate name of waitUntil() ensures that the (asynchronously generated) notification was really displayed earlier than the perform exits and the browser terminates the service-worker.

2.1.4.3. Reply to consumer actions

So as to have the ability to react to consumer actions, a listener for the ‘notificationclick’ occasion have to be arrange. With the ‘occasion’ parameter, this perform receives all information for the notification within the ‘occasion.notification’ property. Consumer-specific information might be handed inside ‘occasion.notification.information’. This information for instance can include an URL to be opened when the consumer clicks on the notification.

perform pnNotificationClick(occasion) {
    console.log('notificationclick occasion: ' + occasion);
    if (occasion.notification.information && occasion.notification.information.url) {
        const promise = purchasers.openWindow(occasion.notification.information.url);
        occasion.waitUntil(promise);
    }
}

The perform purchasers.openWindow() is obtainable for opening a URL within the browser. Right here, too, the waitUntil() have to be used to attend for the decision to finish appropriately earlier than the service-worker might be terminated.

Additional potential actions within the ‘notificationclick’ occasion are mentioned in chapter 2.3 when messages are despatched from the server.

2.2. Obtain and save subscriptions on the server

To obtain and save the subscriptions, a service is about up on the server that receives the information posted by the HTTP request from the consumer and shops it in a database. It should subsequently first be checked whether or not it’s a POST request. As well as, it have to be checked whether or not the content material of the request has really been recognized as JSON information.

If the request is appropriate, the information shall be saved. For the sake of simplicity, we use a SQLite information supplier right here, because it creates its personal information file and can be utilized with out additional configuration. By utilizing the identical information supplier, the subscriptions shall be accessed later to ship the notifications. 

To combine the package deal into your personal system, you need to use the MySQL information supplier or your personal information supplier that implements the PNDataProvider interface.

// solely serve POST request containing legitimate json information
if (strtolower($_SERVER['REQUEST_METHOD']) == 'put up') {
    if (isset($_SERVER['CONTENT_TYPE']) && 
        trim(strtolower($_SERVER['CONTENT_TYPE']) == 'software/json')) {
        // get posted json information
        if (($strJSON = trim(file_get_contents('php://enter'))) === false) {
            $end result['msg'] = 'invalid JSON information!';
        } else {
            $oDP = new PNDataProviderSQLite();
            if ($oDP->saveSubscription($strJSON) !== false) {
                $end result['msg'] = 'subscription saved on server!';
            } else {
                $end result['msg'] = 'error saving subscription!';
            }
        }
    } else {
        $end result['msg'] = 'invalid content material sort!';
    }
} else {
    $end result['msg'] = 'no put up request!';
}
// let the service-worker know the end result
echo json_encode($end result);

2.3. Create and ship notifications

To ship push notifications we’ve got to observe the definitions of the online push protocol (see https://instruments.ietf.org/html/draft-ietf-webpush-protocol-12). Principally, two steps are crucial when creating the push notification.

As a way to determine your self with the push service, a signature have to be transferred utilizing the VAPID key within the header of the request. The notification itself is transmitted in encrypted type and corresponding data can be handed within the header in order that the browser can decrypt the acquired information. If the notification was decrypted appropriately, the browser triggers the ‘push’ occasion to the service-worker.

2.3.1. The VAPID header

As a way to determine with the push service, the server has to signal some data in JSON format with its non-public VAPID key and cross it within the header. The push service verifies this and, if profitable, forwards the notification to the consumer.

The signature is given within the type of a JSON Net Token (JWT). A signed JWT is nothing greater than a string, which consists of three elements separated by dots:

JWTInfo . JWTData . Signature

The primary two strings are JSON formatted information, which should be ‘URL secure base64’ encoded, the third half accommodates the encrypted signature.

JWT Information

This accommodates details about the JWT itself and the encryption algorithm used.

JWT Knowledge

Comprises details about the sender, the recipient (not the ultimate recipient, however the push service!) and the way lengthy the message is legitimate.

Signature

The signature is generated from the primary two unsigned components. To do that, they’re encrypted with the ES256 algorithm (quick for: ECDSA utilizing the P-256 curve and the SHA-256 hash algorithm) utilizing the VAPID key.

The push service now validate the JWT by decrypting the signature utilizing the general public VAPID key and evaluating it with the primary two components.

The whole JWT (i.e. all three components separated by a dot) is handed as authorization within the header. As well as, the general public VAPID key ‘URL secure base64’ coded have to be transferred within the crypto-key worth.

The required VAPID headers are generated with the PNVapid class. The VAPID keys are handed as soon as within the constructor since they don’t change. The tip level (i.e. the recipient) is handed on once more for every notification to be generated.

// data
$aJwtInfo = array('typ' => 'JWT', 'alg' => 'ES256');
$strJwtInfo = self::encodeBase64URL(json_encode($aJwtInfo));

// information
// - origin from endpoint
// - timeout 12h from now
// - topic (e-mail or URL to invoker of VAPID-keys)
$aJwtData = array(
        'aud' => PNSubscription::getOrigin($strEndpoint),
        'exp' => time() + 43200,
        'sub' => $this->strSubject
    );
$strJwtData = self::encodeBase64URL(json_encode($aJwtData));

// signature
// ECDSA encrypting "JwtInfo.JwtData" utilizing the P-256 curve
// and the SHA-256 hash algorithm
$strData = $strJwtInfo . '.' . $strJwtData;
$pem = self::getP256PEM($this->strPublicKey, $this->strPrivateKey);

if (openssl_sign($strData, $strSignature, $pem, 'sha256')) {
    if (($sig = self::signatureFromDER($strSignature)) !== false) {
        $strSignature = self::encodeBase64URL($sig);			
        $aHeaders = array( 
               'Authorization' => 'WebPush ' . 
                                   $strJwtInfo . '.' . 
                                   $strJwtData . '.' . 
                                   $strSignature,
               'Crypto-Key'    => 'p256ecdsa=" . 
                                   self::encodeBase64URL($this->strPublicKey)
            );
    }
}

2.3.2. Encrypt the payload

Because the push notifications are despatched by numerous push service suppliers, the precise consumer information is transmitted in encrypted type. The push service is unable to decrypt and browse this information.

That is outlined within the “Message Encryption for Net Push’ (see https://instruments.ietf.org/html/draft-ietf-webpush-encryption-09).

The strategies which are used throughout encryption are past the scope of this tutorial and are subsequently not defined intimately. You’ll discover a superb clarification within the net push e book by Matt Gaunt (https://web-push-book.gauntface.com) in chapter 4.2.

All required features are supplied by the PNEncryption class. This class additionally gives the extra request headers which are required in order that the notification might be decrypted. Within the constructor, this class requires the general public key and the authentication code that was generated by the browser when subscribing, and naturally the consumer information to be encrypted.

2.3.3. The payload

At this level we are actually going to take a more in-depth have a look at the consumer information that we wish to ship with the notification. As talked about in part 2.1.4, the potential choices that may be handed to the showNotification() perform within the service-worker are defined in additional element now.

Because the format and content material of the payload might be freely outlined (so long as the size of the consumer information doesn’t exceed approx. 4000 characters), I’ve determined to incorporate all data for displaying the notification on the server facet collectively in an object. Along with the title and the goal URL to which we wish to direct the consumer, this object additionally accommodates the entire choices for the showNotification() perform.

Every part collectively is then JSON-encoded and despatched as payload. This offers us the best flexibility to find out the show and habits of the notification from PHP with out having to make modifications to the service employee.

2.3.3.1. The choices of showNotification()

As a way to deal with the consumer with a transparent notification, this could consist at the least of a brief, significant title, a logo with recognition worth (-> ideally an organization or product brand) and a brief, exact textual content.

The title is handed instantly as a parameter, the opposite two values are a part of the choice object. A transparent advice concerning the format of the image can’t be made. In any case, a sq. format needs to be chosen, since most browsers or platforms crop different codecs accordingly.

A dimension of 64dp (px * machine pixel ratio – this provides 192px for a price of three) has confirmed itself. The textual content shouldn’t be longer than about 200 characters. Right here, too, the browsers and platforms differ in behaviour when an extended textual content is supplied. Some restrict the textual content to a sure variety of characters, others to a sure variety of strains. It also needs to be remember right here {that a} textual content that’s too lengthy often doesn’t obtain the mandatory consideration from the consumer.

With the ‘tag’ choice, notifications might be grouped for the consumer. This ensures that solely essentially the most just lately acquired notifications with the identical indicator are exhibited to the consumer so he is not going to be “flooded” with a sequence of a number of messages of the identical sort. If the ‘renotify’ choice can be set, the consumer shall be notified, and the notifications will nonetheless be grouped within the show checklist. If not set, no notification shall be displayed.

The help of the next properties, which might be outlined to format the notification or its behaviour, varies extensively between the a number of browsers/platforms and will subsequently be used with warning.

Picture

URL to a bigger picture, which is often displayed beneath the textual content. Once more, it’s tough to provide a rule about dimension or format.

Badge

URL to a (usually monochrome) badge. The badge is used to higher classify the sender of the message. Up to now, that is solely supported by just a few browsers – most of them show their very own icon.

Further actions

Some browsers enable sure actions to be displayed inside the notification so the consumer can choose considered one of it. The respective javascript code have to be outlined within the service employee within the ‘notificationclick’ occasion. If this performance is used, an alternate show and dealing with ought to at all times be supplied if the browser or the goal system doesn’t help this perform.

An motion is outlined by:
– motion:    inside ID utilized in ‘notificationclick’ occasion.
– title:        textual content to be displayed.
– icon:       [optional] URL to an icon assigned to the motion.

The depend of actions that may be displayed inside a notification range as properly. An fascinating article on this matter might be discovered at https://builders.google.com/net/updates/2016/01/notification-actions.

Timestamp

This lets you set the time when the message was generated. If this feature isn’t set, the time at which the message arrived on the consumer is about.

Require Interplay

This property specifies that consumer interplay is required for the notification. The popup is often displayed instantly and disappears after a sure time. If this feature is activated, the popup stays till the consumer solutions. This property needs to be used fastidiously (for essential or safety points solely) because the consumer could discover it annoying and should block the notifications completely.

Silent

No sound is performed or vibration is triggered.

Vibrate

A vibration sample to run with the show of the notification. A vibration sample have to be an array with at the least one member. The values are occasions in milliseconds the place the even indices (0, 2, 4, and so on.) point out how lengthy to vibrate and the odd indices point out how lengthy to pause. For instance, [300, 100, 400] would vibrate 300ms, pause 100ms, then vibrate 400ms.

Sound

URL to a sound file. Up to now I’ve not discovered a browser that helps this.

2.3.3.2. Prolong the ‘push’ occasion listener within the service-worker

To generate the notification, the PNPayload class gives all strategies to outline the properties described and create the Object.

Since we initially assumed pure textual content as consumer information when creating the service-worker in part 2.1.4, the occasion listener should now be expanded for the information contained within the notification. All that must be finished is to decode the acquired JSON-formatted information and cross it on when calling the showNotification() perform.

perform pnPushNotification(occasion) {
    console.log('push occasion: ' + occasion);
    var strTitle = strDefTitle;
    var oPayload = null;
    var choose = { icon: strDefIcon };
    if (occasion.information) {
        // PushMessageData Object containing the pushed payload
        attempt {
            // attempt to parse payload JSON-string
            oPayload = JSON.parse(occasion.information.textual content());
        } catch (e) {
            // if no legitimate JSON Knowledge take textual content as it's...
            // ... comes possibly whereas testing instantly from DevTools
            choose = {
                icon: strDefIcon,
                physique: occasion.information.textual content(),
            };
        }
        if (oPayload) {
            if (oPayload.title != undefined && oPayload.title != '') {
                strTitle = oPayload.title;
            }
            choose = oPayload.choose;
            if (oPayload.choose.icon == undefined || 
                oPayload.choose.icon == null || 
                oPayload.icon == '') {
                // if no icon outlined, use default
                choose.icon = strDefIcon;
            }
        }
    }
    var promise = self.registration.showNotification(strTitle, choose);
    occasion.waitUntil(promise);
}

2.3.4. Ship the notification through Http-request

The final step is to ship the notification(s) to the respective push companies through HTTP request. As a way to be as unbiased as potential, that is finished instantly utilizing cURL.

To have as little idle time as potential even with numerous notifications to be despatched, all pending messages are first generated fully, encrypted after which despatched utilizing a cURL Multirequest.

Since PHP doesn’t help multithreading per se, that is essentially the most elegant answer with out advanced exterior PHP extensions. In any case notifications have been despatched, the response codes of all requests are learn as a way to filter out any subscriptions which are now not legitimate and, in that case configured, to delete them from the database.

The whole course of to ship notifications

• create the VAPID header signature
• generate the notification payload
• encrypt the payload
• ship through HTTP request
• If crucial, delete expired / now not legitimate subscriptions

is applied in PNServer by utilizing the respective courses.

3. Appendix

3.1. How lengthy is a Subscription legitimate?