Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Web Push protocol allows your application to easily engage users by sending notifications to the browser. The subscription to these notifications are done by the user (opt-in).
The notification types depend on the application. For example, it could be a notification for an internal message or an alert before account closure.
We will see in this documentation that the Web Push API offers several options to customize the notifications by adding buttons, vibration schema, images, urgency indictor and more.
You want to test it? Please go to this demo page to see what your browser already supports.
The subscription is created on client side when the end-user allows your application to send push messages.
On client side (Javascript), you can simply send to your server the object you receive using JSON.stringify
.
Javascript examples to get a Subscription from the web browser are not provided here. Please refer to other resources such as blog posts or library documentation.
A subscription object will look like:
On server side, you can get a WebPush\Subscription
object from the JSON string using the dedicated method WebPush\Subscription::createFromString
.
By default, the content encoding aesgcm
will be used. This encoding indicates how the payload of the notification should be formatted. The PushManager object from the Push API may list all acceptable encodings. In this case, it could be interesting to set these encodings to the Subscription object.
This will result in something like as follow:
The order of supportedContentEncodings
is important. First supported item will be used. If possible, AES128GCM
should be used as prefered content encoding.
The MIT License (MIT)
Copyright (c) 2020-2021 Spomky-Labs
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
After sending a notification, you will receive a StatusReport object.
This status report has the following properties:
The notification
The subscription
The PSR-7 request
The PSR-7 response
Because of the presence of the Request and Response object, the StatusReport object cannot be serialized.
Depending on the status code, you will be able to know if it is a success or not. In case of success, you can directly access the management link (location
header parameter) or the links entity fields in case of asynchronous call. In case of failure, the response code indicates the main reason for rejection (invalid authorization token, expired endpoint...)
One of the failure reasons could be the expiration of the subscription (too old or cancelled by the end-user). This can be checked with the method hasExpired()
. In this case, you should simply delete the subscription as it is not possible to send notifications anymore.
First of all, thank you for contributing.
Bugs or feature requests can be posted online on the GitHub issues section of the project.
Few rules to ease code reviews and merges:
You MUST follow the PSR-12 coding standard.
You MUST run the test suite (see below).
You MUST write (or update) unit tests when bugs are fixed or features are added.
You SHOULD write documentation.
We use the following branching workflow:
Each minor version has a dedicated branch (e.g. v1.1, v1.2, v2.0, v2.1…)
The default branch is set to the last minor version (e.g. v2.1).
To contribute use Pull Requests, please, write commit messages that make sense, and rebase your branch before submitting your PR.
Your PR should NOT be submitted to the master branch but to the last minor version branch or to another minor version in case of bug fix.
PHP 8.0+
A PSR-17 (HTTP Message Factory) implementation
A PSR-18 (HTTP Client) implementation
The JSON
extension
A PSR-3 (Logger Interface) implementation for debugging
Required:
openssl
extension
mbstring
extension
A JWT Provider
Optional:
A PSR-3 (Logger Interface) implementation for debugging
This library provides JWT Provider implementations for web-token and lcobucci/jwt
Required:
openssl
extension
mbstring
extension
Optional:
A PSR-6 (Caching Interface) implementation
A PSR-3 (Logger Interface) implementation for debugging
In the documentation, you will see that methods are called “fluently”.
If you don’t adhere to this coding style, you are free to use the “standard” way of coding. The following example has the same behavior ase above.
To reach the client (web browser), you need to send a Notification to the Subscription.
The Notification should have a payload. In this case, the payload will be encrypted on server side and decrypted by the client.
That payload may be a string or a JSON object. The structure of the latter is described in the next section.
With this feature, a value in seconds is added to the notification. It suggests how long a push message is retained by the push service. A value of 0 (zero) indicates the notification is delivered immediately.
A push message that has been stored by the push service can be replaced with new content. If the user agent is offline during the time the push messages are sent, updating a push message avoids the situation where outdated or redundant messages are sent to the user agent.
Only push messages that have been assigned a topic can be replaced. A push message with a topic replaces any outstanding push message with an identical topic.
For a device that is battery-powered, it is often critical it remains dormant for extended periods.
Radio communication in particular consumes significant power and limits the length of time the device can operate.
To avoid consuming resources to receive trivial messages, it is helpful if an application server can communicate the urgency of a message and if the user agent can request that the push server only forwards messages of a specific urgency.
Be carful with the very-low
urgency: it is not recognized by all Web-Push services
Your application may prefer asynchronous responses to request confirmation from the push service when a push message is delivered and then acknowledged by the user agent. The push service MUST support delivery confirmations to use this feature.