Passer au contenu principal

​
Vue d’ensemble

Ce guide explique comment configurer le Service Worker OneSignal pour les notifications push web.
Si vous utilisez notre plugin WordPress, le fichier Service Worker OneSignal est ajouté automatiquement et vous ne devez pas ajouter ces fichiers à votre site manuellement. Retournez à Configuration WordPress pour plus d’informations.

​
Qu’est-ce qu’un service worker ?

Un Service Worker est un script en arrière-plan qui s’exécute dans un thread séparé de la page principale. Il active des fonctionnalités comme les notifications push, la mise en cache hors ligne et la synchronisation en arrière-plan. Il est installé lorsque votre site l’enregistre et, bien qu’il ne soit pas toujours en cours d’exécution, il peut être réveillé pour gérer des événements (y compris les push) même après que l’utilisateur a quitté la page.

Comment fonctionnent les service workers

​
Comment intégrer le service worker de OneSignal

En suivant notre guide Configuration du SDK Web, vous recevrez le fichier service worker OneSignalSDKWorker.js.

​
Télécharger le fichier .js

Téléchargez le fichier OneSignalSDKWorker.js depuis le tableau de bord OneSignal ou Téléchargez le fichier Service Worker OneSignal ici.

​
Téléverser le fichier .js sur votre serveur

Notre SDK recherche par défaut le fichier OneSignalSDKWorker.js à la racine de votre site, par exemple : https://votresite.com/OneSignalSDKWorker.js Vous pouvez simplement téléverser ce fichier dans le répertoire racine de votre site et revenir au guide Configuration push web pour les prochaines étapes. Cependant, il est recommandé de placer ce fichier OneSignalSDKWorker.js dans un chemin de sous-répertoire vers lequel vous ne lierez jamais d’utilisateurs comme https://votresite.com/push/onesignal/OneSignalSDKWorker.js. Vous pouvez placer ce fichier à la racine, mais il peut entrer en conflit avec d’autres Service Workers que vous avez maintenant ou que vous pourriez ajouter à l’avenir. De plus, le fichier doit être placé dans un chemin d’emplacement permanent qui ne changera jamais. Une fois qu’un Service Worker est enregistré auprès du navigateur, il est difficile de le modifier.

​
Configuration du service worker

Le fichier service worker OneSignal OneSignalSDKWorker.js doit répondre à ces exigences :
  • Le fichier doit être accessible publiquement, ce qui signifie que vous devriez pouvoir naviguer vers le fichier dans un navigateur et voir le code.
  • Le fichier doit être servi avec un content-type de application/javascript; charset=utf-8.
  • Le fichier doit pointer vers la même origine de site (votre domaine de site). Pointer vers un Service Worker sur une origine différente n’est pas autorisé. Pas de CDN ou de sous-domaines.

​
Confirmer que le service worker est configuré correctement

Visitez le service worker dans votre navigateur. Vous devriez voir le code du service worker : importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Exemple du code du service worker

Si vous avez téléversé le fichier OneSignalSDKWorker.js à la racine de votre site (il est accessible à https://votresite.com/OneSignalSDKWorker.js) alors aucune action supplémentaire n’est nécessaire. Cependant, si vous l’avez mis dans un sous-répertoire comme https://votresite.com/push/onesignal/OneSignalSDKWorker.js alors vous devrez définir la portée d’enregistrement comme suit :
  • Configuration de site typique
  • Configuration de code personnalisé
Dans le tableau de bord OneSignal, allez dans les Paramètres > Push & In-App > Paramètres Web de votre applicationSous Paramètres push avancés, activez le commutateur Personnaliser les chemins et noms de fichiers des service workers et saisissez vos données.

Configuration du service worker pour la configuration de site typique

  • Chemin vers les fichiers service worker est le répertoire où le fichier Service Worker OneSignal sera disponible. Si le Service Worker est disponible à : https://votresite.com/push/onesignal/OneSignalSDKWorker.js alors le chemin est : /push/onesignal/
  • Noms de fichiers service worker principal et de mise à jour est le nom du fichier Service worker. Il devrait être OneSignalSDKWorker.js mais si vous l’avez changé, assurez-vous d’utiliser l’extension de fichier .js. Par exemple, si votre serveur force les fichiers à être en minuscules, vous pouvez définir le nom de fichier comme onesignalsdkworker.js
  • Portée d’enregistrement du service worker sont les pages sur lesquelles ce fichier peut fonctionner. Cela devrait être un chemin vers lequel vous ne lierez jamais d’utilisateurs et où vous n’hébergerez jamais de pages maintenant ou à l’avenir. Un exemple de chemin courant : /push/onesignal/ et la portée pourrait être le même chemin ou plus profond comme : /push/onesignal/js/
La configuration du service worker est terminée !Retournez au guide Configuration du SDK Web pour les prochaines étapes.

​
Guide de migration du Service Worker OneSignal

Cette section est uniquement pour les clients qui utilisent déjà OneSignal, ont un grand nombre d’abonnés push web et souhaitent modifier les paramètres du Service Worker OneSignal. Cela n’est pas recommandé sauf si vous avez une raison spécifique de le faire.
Ce guide est uniquement pour les clients qui utilisent déjà OneSignal sur leur site web actuellement et souhaitent déplacer le fichier OneSignalSDKWorker.js vers un chemin ou une portée différent.
Le Service Worker de OneSignal utilise par défaut une portée racine qui peut créer les problèmes suivants pour votre site :
  • Conflit avec une PWA
  • Conflit avec une configuration AMP
  • Conflit avec votre Service Worker de mise en cache, ou toute autre fonctionnalité de Service Worker qui nécessite une portée racine
  • Votre site a des exigences de sécurité qui ne permettent pas au code Service Worker tiers de s’exécuter sur une portée qui contrôle une page que vos utilisateurs visiteront.
Si un ou plusieurs s’appliquent à vous, veuillez suivre ce guide.

​
Choisir une portée de Service Worker OneSignal

Il est recommandé de choisir un chemin de portée de Service Worker vers lequel vous ne lierez jamais un utilisateur, mais qui indique clairement ce qu’il fait. Exemple : /push/onesignal/. De cette façon, votre PWA, AMP ou tout autre ServiceWorker de mise en cache peut contrôler la page qu’un utilisateur visualise pour fonctionner correctement.Il est acceptable de placer plusieurs service workers au même emplacement de chemin, mais DOIVENT avoir un chemin de portée unique.
  • Option 1 : Changer la portée
  • Option 2 : Changer le nom de fichier ou l'emplacement'

​
Changer en toute sécurité la portée du Service Worker OneSignal

Il est recommandé de ne changer que la portée si possible, changer le nom de fichier ou le chemin d’emplacement du Service Worker lui-même a des considérations supplémentaires. Faites très attention aux détails du scénario qui s’applique à vous ainsi qu’à chaque étape pour vous assurer de ne pas perdre d’abonnés ou de rencontrer des problèmes d’affichage de notification

​
Type de configuration 1. Configuration OneSignal par défaut - Portée racine ”/” ET contenu OneSignalSDKWorker.js par défaut

Confirmez que le contenu de votre fichier OneSignalSDKWorker.js est le même que celui trouvé dans Téléchargez le fichier Service Worker OneSignal ici. (Sans aucun autre code non-OneSignal dont vous pourriez avoir besoin)Dans ce cas, vous pouvez changer la portée OneSignal vers ce que vous choisissez pour faire de la place à un autre Service Worker à placer à la portée racine. Voir ci-dessus Personnalisez votre intégration de Service Worker.
Si votre OneSignalSDKWorker.js n’est pas hébergé à la racine de votre domaine aujourd’hui, par exemple vous ne l’avez PAS hébergé comme ceci : https://monsite.com/OneSignalSDKWorker.js alors vous DEVEZ continuer à l’héberger avec l’en-tête Service-Worker-Allowed pendant une période prolongée. (1 an ou plus est recommandé)Si possible, nous recommandons d’ajouter un commentaire dans votre code backend ou votre documentation interne pour vous assurer qu’il ne soit pas accidentellement supprimé.

​
Type de configuration 2. Peu commun - Portée racine ”/” ET OneSignalSDKWorker.js (ou votre nom de fichier configuré) contient OneSignal + autre code ou importScripts

C’est moins courant mais vous avez peut-être déjà fait cela en suivant ce guide OneSignal “Intégration de plusieurs Service Workers”. Si cette configuration répond toujours à toutes vos exigences, il est fortement recommandé de conserver votre configuration telle quelle en raison du déploiement complexe et en deux phases requis pour séparer le fichier ServiceWorker fusionné qui gère les événements push.
Cette section s’applique si vous avez OneSignal ET soit du code personnalisé ou importScript comme suit dans votre Service Worker actuel.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//Et un autre code spécifique au site dans le même fichier exemple.
importScripts("https://site.com/my-other-service-worker.js");
1

Conservez votre code de service worker existant.

Ajoutez un commentaire de code à votre fichier ServiceWorker existant au-dessus de cette ligne importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); pour le conserver pendant une période prolongée. (un an ou plus est recommandé, dépend de combien de temps vous voulez continuer à envoyer des pushs aux utilisateurs qui ne revisitent jamais votre site). Exemple : // CONSERVER jusqu'au AAAA-MM-JJ : Requis pour que les pushs fonctionnent correctement pour les utilisateurs qui n'ont pas revisité pour migrer vers le nouveau ServiceWorker spécifique à OneSignal.
2

Créez un nouveau fichier service worker

Créez un nouveau OneSignalSDKWorker.js dans un répertoire différent, tel que /push/onesignal/ avec la ligne de code unique suivante importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Suivez le guide sur "Personnalisation de votre intégration de Service Worker" pour changer votre portée, nom de fichier et chemin.

4

À ce stade, les nouveaux utilisateurs et les utilisateurs qui reviennent seront automatiquement abonnés au nouveau ServiceWorker OneSignal.

5

Attendez la durée (environ un an) comme indiqué à l'étape 1.

6

Suivez le guide OneSignal - Supprimer les utilisateurs pour supprimer les utilisateurs plus anciens que la chronologie que vous avez choisie.

7

Supprimez le commentaire du service worker original

Enfin, supprimez la ligne importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); avec le commentaire de votre ServiceWorker racine original.

​
Migration de la portée du ServiceWorker OneSignal - FAQ

Pourquoi dois-je continuer à héberger l’URL du fichier ServiceWorker original si je change le nom ou le chemin d’emplacement ?
Cela est requis pour les utilisateurs qui n’ont pas revisité votre site pour que le nouveau nom de fichier soit récupéré. Le fichier ServiceWorker original sera récupéré par le navigateur chaque fois que vous envoyez un push (si le délai d’expiration du cache est dépassé, le cache maximum est de 24 heures). Vous verrez un pic d’erreurs 404 renvoyées par votre fournisseur d’hébergement lors de l’envoi d’un push si le fichier ServiceWorker original n’est pas disponible. Cela peut entraîner plus de requêtes vers votre serveur. Cela signifie également que ces utilisateurs n’obtiendront pas les nouvelles fonctionnalités et correctifs de OneSignal.