OneSignal ou comment envoyer simplement des notifications push aux navigateurs
Depuis juin 2016, la plupart des navigateurs (Chrome, Firefox et Opera) permettent l'envoi de notifications push. Vous pouvez par exemple informer vos abonnés de la publication d'une news sur votre site, ou de promotions flash sur votre boutique. Pour Internet Explorer, rien n'est prévu. Quant à  Edge, il supporte enfin les notifications depuis décembre 2017 !
L'utilisateur se voit proposer une boîte de dialogue lui laissant 3 choix : accepter, refuser, remettre à plus tard (ce dernier choix s'obtient en cliquant la croix).
Il existe plusieurs librairies php permettant d'envoyer des notifications. Soit elles exigent Composer, soient elles s'appuient sur un service tiers payant.
OneSignal est gratuit et propose un tableau de bord complet ainsi qu'une API. Un système de filtres et de segments permet de cibler les destinataires. L'envoi de notifications et le nombre de destinataires est illimité. L'interface est en Anglais et la documentation, très bien faite (et c'est suffisamment rare pour le signaler).
Il existe également d'autres services gratuits tels que PushCrew et SendPulse, que je n'ai eu l'occasion de tester.
UPDATE 07/05/2018 : OneSignal a complètement relooké son interface, j'ai donc dû refaire toutes les captures
Inscription
Il suffit d'une adresse email, d'un mot de passe, et d'un nom de société.
Arrivée d'un mail « Confirmation instructions » en provenance de contact@onesignal.com comportant le lien de confirmation, qui nous mène à l'accueil de notre tableau de bord…
L'interface est moderne et clean, très flat design.
Il nous faut ensuite ajouter une application.
Ajout d'une application
A l'issue du tuto d'accueil, OneSignal propose de créer sa première application. La 1e étape consiste à donner un nom à cette nouvelle application.
Ensuite, il faut configurer au moins une plateforme. Ici, c'est web push qui m'intéresse, mais il est possible d'en sélectionner plusieurs. Par défaut, toutes les plateformes sont inactives.
OneSignal demande ensuite de choisir le type d'intégration et de fournir les informations du site qui va émettre les notifications.
Un lien vers un fichier icône est demandé. A noter que ce fichier doit mesurer au minimum 80×80 pixels (la taille recommandée étant de 192×192)
Les sites qui ne sont pas en HTTPS sont désavantagés. Les demandes de permission s'afficheront dans une grosse boîte de dialogue modale au lieu du prompt du navigateur. Les notifications apparaîtront comme provenant d'un sous-domaine de onesignal.com au lieu de notre domaine…
Et si ensuite, vous migrez votre site en HTTPS, il vous faudra créer une toute nouvelle application, car le changement d'URL est impossible…
Si on scrolle dans la page, les blocs suivants permettent de paramétrer le message qui s'affiche quand le site va demander la permission d'envoyer des notifications.
Le clic sur Add a prompt ouvre ce popup
Ensuite, dans Welcome Notifications, on peut paramétrer le message qui s'affiche quand l'utilisateur a accepté les notifications (par exemple pour afficher un message en Français pour les sites francophones).
Le tout dernier bloc Advanced permet un paramétrage plus fin.
Quand on a terminé, ne pas oublier de cliquer sur Save.
Pour Safari, il faudra saisir le nom du site et l'URL (sans le slash derrière). Ce qui est étrange, c'est que je pensais que Safari ne supportait pas les notifications web push. Ne possédant pas de Mac, je n'ai pas pu le vérifier…
Si, en plus, vous souhaitez couvrir les applications mobiles, il faudra fournir les clés (Android) et certificat (iOS) qui vont bien…
Clés
Comme pour toute API, il vous faut des clés !
Si votre site est en HTTPS, vous êtes invités à télécharger un fichier zip nommé OneSignal-Web-SDK-HTTPS-Integration-Files.zip. Il contient 3 fichiers : manifest.json, OneSignalSDKUpdaterWorker.js et OneSignalSDKWorker.js. Il faut les mettre en ligne à la racine du site.
Dans Settings > Keys & IDs, on retrouve la OneSignal App ID (au format UUID) et la REST API Key.
Ajouter le code d'abonnement au site
Ce bout de code javascript se charge de proposer le popup d'abonnement aux utilisateurs de votre site. Vous allez avoir besoin de votre OneSignal App ID (à insérer à la place de xxx à la suite de appId:).
Si votre site n'est pas en HTTPS
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async='async'></script> <script> var OneSignal = window.OneSignal || []; OneSignal.push(["init", { appId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", autoRegister: true, // true pour automatiquement afficher la demande aux visiteurs subdomainName: 'SUBDOMAIN_NAME_SEE_STEP_1.4', httpPermissionRequest: { enable: true }, notifyButton: { enable: true // false pour masquer le bouton de notification } }]); </script>
S'il est en HTTPS
<link rel="manifest" href="/manifest.json" /> <script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script> <script> var OneSignal = window.OneSignal || []; OneSignal.push(function() { OneSignal.init({ appId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", }); }); </script>
Comme dernière étape, OneSignal nous demande d'aller sur notre site et d'ajouter notre premier utilisateur.
Dans le cas d'un site ne supportant pas le HTTPS, après cet ajout et un rechargement de la page, le navigateur demande :
Â
On remarque que l'URL monsite.onesignal.com est mentionnée.
Dans le cas d'un site en HTTPS, l'infobulle est la même, mais cette fois-ci la vraie URL du site est mentionnée.
Ajouter un utilisateur
Site ne supportant pas le HTTPS
Si on clique sur le bouton « Autoriser », une fenêtre modale confirme l'abonnement.
A ce stade, l'abonné n'apparaît pas encore dans la liste des All users de notre tableau de bord…
Au clic sur « Close », un tout petit popup apparaît de manière très fugace en bas à gauche de l'écran.
Puis, une 1e notification fait son apparition, pour remercier le nouvel abonné :
Sites en HTTPS
Pas de fenêtre ni de popup rapide, on a simplement la notification de remerciement.
Ensuite, une petite icône en forme de cloche située dans le coin inférieur droit du site indique à l'utilisateur qu'il est abonné aux notifications du site.
Et, là seulement, l'utilisateur apparaîtra dans la liste des users…
Gestion des utilisateurs
Pour voir les utilisateurs, il faut cliquer sur le lien « View users » du segment voulu (pas sur le nom du segment, sinon on arrive sur le formulaire d'édition du segment).
On peut dès lors ajouter cet utilisateur au utilisateurs de test en cliquant sur le bouton gris Options et en choisissant « Add to test users ».
Au clic sur Add, l'écran passe automatiquement sur la vue filtrée Test users.
Envoi d'un message
OneSignal offre la possibilité d'envoyer à tous le monde, à des segments particuliers ou aux devices de test.
Cliquer sur New Push. Autrefois, l'interface d'envoi était sous la forme d'un assistant aux nombreuses étapes. Désormais, tout est rassemblé sur une seule et même page. Chaque étape se trouve dans un bloc.
Choix du segment des utilisateurs destinataires :
Et même de choisir à quel device de test l'envoyer (à condition d'avoir au préalable défini un utilisateur dans le segment test).
Ensuite, nous allons rédiger notre message. L'aperçu se met à jour en direct.
L'anglais est utilisé par défaut, mais il est également possible d'ajouter une version pour chacune des langues que l'on cible en cliquant sur l'icône en forme de crayon à côté de « English ».
L'étape suivante permet de définir les options : icône, plateforme etc
Puis OneSignal propose de choisir le moment où la notification va être délivrée.
Cliquer sur le bouton Confirm en bas de page
Et enfin, petit récap avant d'envoyer (les détails sont repliés par défaut)…
Au clic sur « Send message », le navigateur-cible affiche la notification ! Un clic sur la notification emmène vers la page du site. Si le navigateur n'était pas ouvert à ce moment-là , la notification sera délivrée à son prochain lancement.
Tandis que OneSignal redirige vers un écran de stats des messages envoyés.
Envoi de la notification via l'API
Cet assistant d'envoi de notification est très complet et très joli… mais un peu long à utiliser. Ce qui m'intéresse, c'est que mon site envoie tout seul ses notifications… Pour cela, on va utiliser l'API.
L'utilisation de l'API passe par l'utilisation de curl. Vous ne pourrez donc pas l'utiliser sur un hébergement Free.fr
La REST API Key va enfin nous servir… on va la passer dans un appel à  curl_setopt(), à la suite de Authorization: Basic.
Le code exemple fourni ici (cliquer l'onglet PHP) est simple, pur procédural php, comme j'aime. On définit une fonction sendMessage() à laquelle on passe en paramètre $texte le message qu'on souhaite afficher en notification.
Dans l'array $content, la clé « en » est la seule obligatoire. Comme mon site est en anglais, je n'ai pas eu besoin d'en ajouter une autre pour un langage supplémentaire.
<?php function sendMessage($texte){ $content = array( "en" => utf8_encode($texte) ); $fields = array( 'app_id' => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'included_segments' => array('All'), 'data' => array("foo" => "bar"), 'contents' => $content ); $fields = json_encode($fields); print("\nJSON sent:\n"); print($fields); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://onesignal.com/api/v1/notifications"); curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json; charset=utf-8', 'Authorization: Basic XXXxXXXxXxXxX2XxXx0xXXXxXXx5XXXxXXXxXxX5XXXxXxXx')); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); $response = curl_exec($ch); curl_close($ch); return $response; } $response = sendMessage(); $return["allresponses"] = $response; $return = json_encode( $return); print("\n\nJSON received:\n"); print($return); print("\n"); ?>
On peut laisser ‘data' => array(« foo » => « bar »), même si je ne l'utilise pas (le champ data représente du contenu additionnel qui est retourné à notre application).
Les appels à  print() sont uniquement pour les tests, afin de voir comment cela fonctionne, par exemple à quoi ressemble la structure du json qui est envoyé à l'API de OneSignal. Vous les enlèverez ensuite…
Attention à l'encodage ! json_encode() n'aime pas les caractères accentués s'ils n'ont pas été au préalable protégés par un utf8_encode(). Sinon, le message envoyé sera vide et vous aurez une erreur « Notification contents must not be null for any languages »
Pour envoyer à nos test users, on change la valeur de $fields[‘included_segments'] de « All » à « Test Users ». Mais il faut d'abord réunir ces users de test en un segment. Sinon vous aurez l'erreur « All included players are not subscribed »
JSON sent: {"app_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","included_segments":["Test users"],"data":{"foo":"bar"},"contents":{"en":"First notification through API"}} JSON received: {"allresponses":"{\"id\":\"\",\"recipients\":0,\"errors\":[\"All included players are not subscribed\"]}"}
Créer un segment
Aller dans Users et cliquer sur le bouton « New Segment » sous la ligne « Built-In Segments ».
Nommer ce segment « Test Users » (ce qui a pour effet de faire disparaître la liste de règles qui est remplacée par le bouton « Add filter »).
Faire réapparaître la liste de règles en cliquant sur « Add filter » et choisir la dernière option Test users.
Attention, le système est case sensitive ! « Test Users » sera compris différemment de « Test users »
Et quand l'envoi php fonctionne, voici ce que l'on obtient :
JSON sent: {"app_id":"f1157b39-5ed4-4bdd-a7f9-3bd4288aedaf","included_segments":["Test Users"],"data":{"foo":"bar"},"contents":{"en":"Second notification through API test accentu\u00e9"}} JSON received: {"allresponses":"{\"id\":\"ff689818-edce-448e-ae9e-f664d4e769ed\",\"recipients\":2}"}
Pour faire fonctionner le script pour de vrais abonnés, il ne reste plus qu'à commenter tous les print() et à remettre ‘included_segments' à la valeur « All ».
Il n'y a semble-t-il pas de limite de longueur pour le message. Il sera simplement tronqué.
Les messages envoyés
OneSignal indique le statut des messages envoyés, à quelle heure, le nombre de destinataires, quel pourcentage a été cliqué, etc
Afficher l'id du navigateur abonné (en javascript)
Petit bonus, un script qui vous permet d'afficher dans la console l'id d'abonnement de votre navigateur (les deux syntaxes sont équivalentes, à vous de choisir celle que vous préférez).
OneSignal.push(function() { // 1e syntaxe OneSignal.getUserId(function(userId) { console.log("OneSignal User ID:", userId); }); //2e syntaxe OneSignal.getUserId().then(function(userId) { console.log("OneSignal User ID:", userId); }); });
Ce qui va donner dans la console :
OneSignal User ID: 270a35cd-4dda-4b3f-b04e-41d7463a2316
(si l'id est 270a35cd-4dda-4b3f-b04e-41d7463a2316 bien entendu)
Sources
Comment envoyer des notifications push sur Chrome et Firefox ?