Search…
The Notification
To reach the client (web browser), you need to send a Notification to the Subscription.
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create();
Copied!
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.
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create()
5
->withPayload('Hello world')
6
;
Copied!

TTL (Time-To-Live)

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.
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create()
5
->withTTL(3600)
6
;
Copied!

Topic

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.
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create()
5
->withTopic('user-account-updated')
6
;
Copied!

Urgency

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.
Urgency
Device State
Examples
very-low
On power and Wi-Fi
Advertisements
low
On either power or Wi-Fi
Topic updates
normal
On neither power nor Wi-Fi
Chat or Calendar Message
high
Low battery
Incoming phone call or time-sensitive alert
Be carful with the very-low urgency: it is not recognized by all Web-Push services
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create()
5
->veryLowUrgency()
6
->lowUrgency()
7
->normalUrgency()
8
->highUrgency()
9
;
Copied!

Asynchronous Response

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.
1
<?php
2
use WebPush\Notification;
3
4
$notification = Notification::create()
5
->async() // Prefer async response
6
->sync() // Prefer sync response (default)
7
;
Copied!
The async mode is not recognised by all Web Push services. In case of failure, you should try sending syncnotifications.

JSON Messages

As mentioned in the overview section, the specification defines a structure for the payload. This structure contains properties that the client should be understood and render an appropriate way.
The library provides a WebPush\Message class with convenient methods to ease the creation of a message.
1
<?php
2
use WebPush\Action;
3
use WebPush\Message;
4
use WebPush\Notification;
5
6
$message = Message::create('This is the title', null, true)
7
->mute() // Silent
8
->unmute() // Not silent (default)
9
10
->auto() //Direction = auto (default)
11
->ltr() //Direction = left to right
12
->rtl() //Direction = right to left
13
14
->addAction(Action::create('alert', 'Click me!'))
15
16
->interactionRequired()
17
->noInteraction()
18
19
->renotify()
20
->doNotRenotify() // Default
21
22
->withBody('Hello World!')
23
24
->withIcon('https://…')
25
->withImage('https://…')
26
->withData(['foo' => 'BAR']) // Arbitrary data
27
->withBadge('badge1')
28
->withLang('fr-FR')
29
->withTimestamp(time())
30
->withTag('foo')
31
32
->vibrate(300, 100, 400)
33
34
->toString() // Converts the Message object into a string
35
;
36
37
$notification = Notification::create()
38
->withPayload($message)
39
;
Copied!
Please note that the second and the third parameters are needed for v1.1+ branch but bill be removed in v2.0.
The resulting notification payload will look like as follow:
1
{
2
"title":"This is the title",
3
"options":{
4
"actions":[
5
{
6
"action":"alert",
7
"title":"Click me!"
8
}
9
],
10
"badge":"badge1",
11
"body":"Hello World!",
12
"data":{
13
"foo":"BAR"
14
},
15
"dir":"rtl",
16
"icon":"https://…",
17
"image":"https://…",
18
"l ang":"fr-FR",
19
"renotify":false,
20
"requireInteraction":false,
21
"silent":false,
22
"tag":"foo",
23
"timestamp":1629145424,
24
"vibrate":[
25
300,
26
100,
27
400
28
]
29
}
30
}
Copied!
On client side, you can easily load that payload and display the notification:
1
const {title, options} = payload;
2
const notification = new Notification(title, options);
Copied!