Name: Tremplin Numérique
Price range: $$$

L’API Web Push vous permet d’envoyer des notifications push aux navigateurs Web et aux API. Bien que la majeure partie de la logique se déroule dans le navigateur, vous avez toujours besoin d’un composant côté serveur pour générer vos notifications. Voici comment implémenter un backend Web Push en utilisant PHP.

Sommaire

Conditions préalables

Pour les besoins de ce didacticiel, nous supposerons que vous connaissez les bases de la création d’API HTTP en PHP. Vous devrez exposer quelques points de terminaison publics à l’aide de votre infrastructure Web. Ceux-ci seront appelés par le JavaScript de votre navigateur pour enregistrer et désenregistrer des appareils.

Cet article n’abordera pas le code côté navigateur ni son fonctionnement. Vous devrez mettre en place un service worker qui répond aux événements push entrants et affiche une notification à l’utilisateur.

À un niveau élevé, le flux Web Push ressemble à ceci :

Un abonnement push est enregistré dans le navigateur. Le navigateur envoie une URL de point de terminaison unique à votre JavaScript.
Votre JavaScript envoie les données d’abonnement à votre serveur et identifie l’utilisateur auquel il s’applique.
Lorsque votre backend doit envoyer une notification push, créez une charge utile et envoyez-la à l’URL du point de terminaison signalée dans le cadre des données d’abonnement.
Le navigateur de l’utilisateur recevra la charge utile via la plate-forme de livraison de notification du fournisseur. Votre service worker JavaScript gère l’événement qui en résulte et utilise l’API de notification du navigateur pour alerter l’utilisateur.

Voici comment implémenter les aspects côté serveur des étapes 1 à 3.

Obtenir la configuration

Nous utiliserons le web-push Forfait Packagiste par minishlink. Cela fait abstraction des interactions avec chaque plate-forme de notification de navigateur afin que vous n’ayez pas à distinguer manuellement les types de points de terminaison.

Ajoutez le package à votre projet à l’aide de Composer :

composer require minishlink/web-push

Pour utiliser la dernière version, vous avez besoin de PHP 7.2 ou supérieur avec le gmp, mbstring, curl, et openssl prolongements. Si vous devez utiliser une ancienne version de PHP, verrouillez le package sur une version antérieure pour maintenir la compatibilité.

La bibliothèque expose un noyau WebPush class avec des méthodes qui vous permettent d’envoyer des notifications individuellement ou par lots. Les abonnements sont représentés par des instances du Subscription classer.

Fournir des clés VAPID

La confiance dans l’écosystème Web Push conforme aux normes est renforcée par l’utilisation de clés VAPID. Votre serveur a besoin d’une paire de clés VAPID pour pouvoir s’authentifier auprès des navigateurs. La clé publique doit être exposée via un point de terminaison d’API.

Vous pouvez générer un jeu de clés VAPID à l’aide de la web-push emballer:

use MinishlinkWebPushVAPID;
 
$keyset = VAPID::createVapidKeys();
 
// public key - this needs to be accessible via an API endpoint
echo $keyset["publicKey"];
 
// private key - never expose this!
echo $keyset["privateKey"];
 
file_put_contents("vapid.json", json_encode($keyset));

Générez des clés pour votre système et stockez-les dans un emplacement persistant. Ajoutez un point de terminaison d’API afin que votre JavaScript côté client puisse récupérer la clé publique. Cela sera utilisé pour configurer l’abonnement push du navigateur. L’appareil de l’utilisateur acceptera les événements push entrants s’ils ont été signés à l’aide de la clé privée VAPID correspondante.

Enregistrement des abonnements push

L’étape suivante de la séquence consiste à recevoir des demandes d’abonnement push de vos clients. Une fois que le navigateur a confirmé un nouvel abonnement push, votre JavaScript doit envoyer l’URL du point de terminaison de l’abonnement et les clés d’authentification associées à votre serveur. Stockez ces détails avec l’ID de l’utilisateur afin de pouvoir récupérer tous les appareils enrôlés push liés à l’utilisateur ultérieurement.

Nous omettons les exemples de code pour cette étape car l’implémentation dépend de votre couche de stockage de données et des valeurs envoyées par votre JavaScript. En règle générale, il s’agira d’une représentation JSON d’un PushSubscription objet. Vous avez besoin d’un ensemble simple de points de terminaison d’API CRUD basés sur une base de données pour créer un abonnement, remplacer un abonnement existant et demander une suppression lorsque l’utilisateur se désabonne.

Préparation des abonnements

Une fois qu’un client est enregistré avec succès, vous pouvez commencer à envoyer des notifications en utilisant le web-push une bibliothèque. Commencez par créer une instance du WebPush classer:

use MinishlinkWebPushWebPush;
 
$webPush = new WebPush([
    "VAPID" => [
        "subject" => "https://example.com",
        "publicKey" => "VAPID_Public_Key_Here",
        "privateKey" => "VAPID_Private_Key_Here"
    ]
]);

Vous pouvez en réutiliser un WebPush instance chaque fois que vous envoyez une notification. La bibliothèque doit être configurée avec le jeu de clés VAPID que vous avez généré précédemment. Les clés doivent être encodées en Base64, mais cela est géré pour vous si vous les créez avec la bibliothèque.

Le VAPID subject sert à identifier votre serveur et ses coordonnées. Vous pouvez fournir une URL de site Web ou un mailto: lien d’adresse e-mail.

Ensuite, vous devez récupérer l’abonnement push auquel vous allez envoyer. Utilisez votre système d’accès aux données pour rechercher les URL de point de terminaison push associées à l’utilisateur auquel vous souhaitez envoyer. Convertissez chaque abonnement en un Subscription exemple:

use MinishlinkWebPushSubscription;
 
// Get user's push data...
// SELECT * FROM push_subscriptions WHERE user_id = 123456
 
$subscription = Subscription::create([
    "endpoint" => "https://fcm.google.com/...",
    "contentEncoding" => "aesgcm",
    "authToken" => "<auth token from JavaScript PushSubscription object>"
    "keys" => [
        "auth" => "<auth token from JavaScript PushSubscription object>",
        "p256dh" => "<p256dh token from JavaScript PushSubscription object>"
    ]
]);

Les auth propriété de la PushSubscription est répété deux fois pour faire face à deux versions différentes de la spécification utilisée par les services de navigateur. La propriété P256DH est une autre clé publique qui doit être fournie lorsqu’elle est définie sur l’abonnement.

Les web-push La bibliothèque est compatible avec les points de terminaison push Chrome et Firefox. Il fonctionnera également avec toute autre implémentation Web Push qui répond à la norme actuelle.

Envoi d’une notification

Maintenant, combinez votre WebPush et Subscription instances pour envoyer une notification :

$result = $webPush -> sendOneNotification(
    $subscription,
    json_encode([
        "message" => "Demo notification",
        "foo" => "bar"
    ])
);

Appel sendOneNotification() fournit une livraison immédiate pour une seule notification. La charge utile dans ce cas est un tableau encodé JSON avec deux propriétés. C’est à vous de décider quelles données vous envoyez et le format que vous utilisez – votre client JavaScript les reçoit telles quelles et peut les interpréter si nécessaire.

L’envoi d’une notification renvoie une classe de résultat qui vous permet de vérifier si l’opération a réussi :

if ($result -> isSuccess()) {
    // all good
}
else {
 
    // something went wrong
    error_log($result -> getReason());
 
    // provides raw HTTP response data
    error_log($result -> getResponse());
 
}

Vous pouvez prendre des mesures pour réessayer ou annuler la livraison si une erreur se produit.

Les abonnements aux notifications peuvent également expirer. Appeler le isSubscriptionExpired() sur une classe de résultat pour déterminer si c’est la raison de l’échec. Vous pouvez supprimer l’abonnement de votre base de données dans ce scénario, en vous assurant de ne rien envoyer d’autre à un point de terminaison mort.

Notifications de lot

Les notifications peuvent être regroupées pour être livrées avec un seul appel de méthode :

$webPush -> queueNotification($subscription, ["msg" => "first"]);
$webPush -> queueNotification($subscription, ["msg" => "second"]);
 
foreach ($webPush -> flush() as $i => $result) {
    echo ("Notification $i was " . ($result -> isSuccess() ? "sent" : "not sent"));
}

Ceci est utile lorsque vous savez que vous allez envoyer un grand nombre de notifications dans un court laps de temps. Mettez en file d’attente toutes vos charges utiles et laissez web-push les livrer de manière optimale.

Vous pouvez limiter le nombre de notifications envoyées en un seul flush() en passant un entier à la méthode :

$webPush -> flush(100);     // send 100 messages

La valeur par défaut est 1000.

Options de notification

sendOneNotification() et queueNotification() acceptez les options suivantes comme troisième argument du tableau :

TTL – Contrôle la durée pendant laquelle la plate-forme de notification du navigateur conservera la notification si elle ne peut pas être transmise immédiatement à l’appareil de l’utilisateur. Si l’appareil de l’utilisateur est hors ligne, les plates-formes essaient par défaut de le livrer pendant les quatre semaines suivantes. Si vous envoyez une notification qui ne sera pas pertinente la semaine prochaine, ajustez la durée de vie en conséquence afin que l’utilisateur ne voie pas de contenu obsolète.
urgency – Accepte normal, low ou very-low comme valeurs. Certaines plates-formes peuvent l’utiliser pour ajuster la fréquence de livraison des notifications. Les appareils qui entrent en mode d’économie de batterie peuvent suspendre la livraison de notifications non urgentes.
batchSize – Cela a le même effet que l’argument de flush() décrit ci-dessus.

Vous pouvez configurer les valeurs d’option par défaut en utilisant le deuxième argument de la WebPush constructeur:

$webPush = new WebPush(["VAPID" => [...]], ["TTL" => 3600]);

Sommaire

Les web-push La bibliothèque facilite l’envoi de notifications Web Push à l’aide de PHP. Vous obtenez une couche d’abstraction au-dessus des différentes plates-formes de navigateur qui prend en charge le traitement par lots, la gestion des erreurs et toutes les fonctionnalités Web Push.

Le mécanisme Web Push est un système de navigateur inhabituel car il dépend des composants distants côté serveur que vous fournissez vous-même. Cela peut le faire paraître opaque et technique. En pratique, créer un backend PHP simple est simple et rapide ; l’implémentation frontale est généralement l’aspect qui prend le plus de temps, en particulier si vous n’utilisez pas déjà les fonctionnalités de service worker.