Passer au contenu principal
Le OneSignal service worker (OneSignalSDKWorker.js) est un fichier JavaScript hébergé sur votre serveur, nécessaire pour les notifications push web. Il permet à votre site de recevoir et d’afficher des notifications, même lorsque l’utilisateur n’est pas sur votre page.
Diagram showing the OneSignal service worker receiving a push event and displaying a notification
Si vous utilisez notre plugin WordPress, le service worker est ajouté automatiquement. Ignorez ce guide et revenez à la configuration WordPress.

​
Configuration du service worker

Créez un fichier OneSignalSDKWorker.js dédié pour les notifications push OneSignal. Si votre site dispose déjà d’un service worker et que vous souhaitez utiliser un seul fichier, consultez plutôt Combiner plusieurs service workers.
1

Télécharger ou créer OneSignalSDKWorker.js

Téléchargez le fichier depuis le tableau de bord OneSignal lors de la configuration du Web SDK ou depuis GitHub.Vous pouvez également créer un fichier nommé OneSignalSDKWorker.js avec la ligne de code suivante :
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
Vous pouvez renommer le fichier si nécessaire (p. ex., onesignalsdkworker.js). Dans ce cas, remplacez simplement OneSignalSDKWorker.js dans ce guide par votre nom de fichier.
2

Téléverser sur votre serveur web

Placez OneSignalSDKWorker.js sur votre serveur de manière à ce qu’il soit accessible publiquement via HTTPS. Le fichier ne doit pas nécessiter d’authentification ou de connexion pour y accéder.Recommandé : Hébergez le fichier dans un sous-répertoire dédié qui ne servira jamais de pages, tel que /push/onesignal/. Cela évite les conflits avec d’autres service workers sur votre site (p. ex., un service worker de PWA ou AMP) et maintient la stabilité du chemin URL.
  • Exemple : https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
Alternative : Le OneSignal Web SDK recherche par défaut le fichier à la racine de votre site (https://yoursite.com/OneSignalSDKWorker.js). Vous pouvez téléverser le fichier dans le répertoire racine, mais il peut entrer en conflit avec d’autres service workers nécessitant une portée racine. Par exemple, si vous utilisez une PWA, placez OneSignalSDKWorker.js dans un sous-répertoire.
Choisissez un chemin URL permanent. Une fois qu’un navigateur enregistre un service worker à une URL donnée, changer cette URL nécessite une migration.
3

Vérifier que le fichier est accessible

Accédez à l’URL du fichier dans votre navigateur (p. ex., https://yoursite.com/push/onesignal/OneSignalSDKWorker.js).Vous devriez voir la ligne importScripts de l’Étape 1 :
Browser displaying the single importScripts line inside OneSignalSDKWorker.js
Si vous voyez une erreur 404, une page vide ou une invite de connexion, le fichier n’est pas correctement téléversé ou se trouve derrière une authentification.
4

Configurer le chemin du SDK (sous-répertoire uniquement)

Si vous avez placé le fichier à la racine de votre site, aucune configuration supplémentaire n’est nécessaire — passez à l’étape suivante.Si vous avez placé le fichier dans un sous-répertoire, indiquez au SDK où le trouver :

​
Configuration de site typique

  1. Dans le tableau de bord OneSignal, accédez à Paramètres > Push & In-App > Paramètres web.
  2. Sous Paramètres push avancés, activez Personnaliser les chemins et noms de fichiers du service worker.
OneSignal dashboard fields for service worker path, filename, and registration scope
ChampDescriptionExemple
Path to service worker filesRépertoire où est hébergé OneSignalSDKWorker.js./push/onesignal/
Service worker filenameNom du fichier .js.OneSignalSDKWorker.js
Service worker registration scopeChemin URL contrôlé par le service worker. Doit être au niveau ou en dessous du répertoire où le fichier est hébergé. Utilisez un chemin qui ne sert jamais de pages orientées utilisateur./push/onesignal/

​
Configuration de code personnalisé

Passez serviceWorkerPath et serviceWorkerParam dans votre appel OneSignal.init() :
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>
ParamètreDescriptionExemple
serviceWorkerPathChemin relatif depuis la racine du site vers le fichier .js (sans barre oblique initiale)."push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scopeChemin URL contrôlé par le service worker. Doit être au niveau ou en dessous du répertoire où le fichier est hébergé. Utilisez un chemin qui ne sert jamais de pages orientées utilisateur."/push/onesignal/"
5

Vérifier les exigences du service worker

Le fichier OneSignalSDKWorker.js doit satisfaire toutes les exigences suivantes. Si l’une d’elles n’est pas respectée, les notifications push ne fonctionneront pas.
ExigenceDétails
Accessible publiquementAccédez à l’URL du fichier dans un navigateur et confirmez que vous voyez le code JavaScript.
Type de contenu correctLe serveur doit retourner Content-Type: application/javascript; charset=utf-8.
Même origineLe fichier doit être hébergé sur le même domaine que votre site. Les CDN et sous-domaines ne sont pas autorisés. Voir MDN : Enregistrement de votre worker.
HTTPSLes service workers nécessitent un contexte sécurisé. localhost est la seule exception pendant le développement.
La configuration du service worker est terminée.

Configuration du SDK Web

Continuez avec le guide de configuration du SDK Web pour les prochaines étapes.

​
Combiner plusieurs service workers

Chaque fichier service worker sur votre site est enregistré à une portée — un chemin URL qui détermine quelles pages il contrôle. Un seul service worker peut être actif à une portée donnée. Si vous avez déjà un service worker (par exemple, une PWA ou un worker de mise en cache) et souhaitez qu’OneSignal partage le même fichier, vous pouvez les combiner.
Conserver les service workers dans des fichiers séparés avec des portées séparées est plus simple à maintenir et évite les conflits. Ne les combinez que si votre configuration nécessite un fichier service worker unique.
Pour combiner, ajoutez la ligne importScripts de OneSignal à votre fichier service worker existant : 
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");
Après la combinaison, mettez à jour la configuration OneSignal pour pointer vers votre fichier service worker existant. Suivez l’Étape 4 : Configurer le chemin du SDK en utilisant le chemin et le nom de fichier de votre fichier combiné.

​
Guide de migration

Cette section est destinée aux clients OneSignal existants qui doivent modifier le chemin du fichier service worker, le nom de fichier ou la portée. Ne suivez pas ces étapes sauf si vous avez une raison spécifique de modifier votre configuration actuelle.
Raisons de migrer :
  • Le OneSignal service worker avec portée racine entre en conflit avec une Progressive Web App (PWA)
  • Le service worker entre en conflit avec AMP ou un autre service worker de mise en cache
  • Les politiques de sécurité interdisent le code de service worker tiers à portée racine
Option 1 : Changer uniquement la portée (recommandé)Changer uniquement la portée est la migration la plus sûre. Le fichier reste à son URL actuelle, de sorte que les abonnés existants continuent de recevoir des notifications sans interruption.Si votre fichier contient uniquement du code OneSignalConfirmez que OneSignalSDKWorker.js contient uniquement :
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
Mettez à jour la portée en utilisant le tableau de bord ou serviceWorkerParam comme décrit dans l’Étape 4 : Configurer le chemin du SDK. Aucune autre modification n’est nécessaire.
Si OneSignalSDKWorker.js n’est pas hébergé à la racine de votre domaine aujourd’hui, vous devez continuer à l’héberger à son URL actuelle avec l’en-tête Service-Worker-Allowed pendant au moins un an. Ajoutez un commentaire dans votre code backend ou votre documentation interne pour que le fichier ne soit pas accidentellement supprimé.
Si votre fichier contient OneSignal + autre codeVotre service worker peut inclure des appels importScripts supplémentaires (p. ex., suite à la combinaison de plusieurs service workers). Si votre configuration actuelle fonctionne toujours, conservez-la telle quelle — séparer un service worker fusionné nécessite un déploiement en deux phases.Si vous devez les séparer :
1

Ajouter un commentaire de rétention au fichier existant

Au-dessus de la ligne importScripts de OneSignal dans votre service worker actuel, ajoutez :
// KEEP until YYYY-MM-DD: Required for push delivery to subscribers who have not revisited.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
Définissez la date à au moins un an dans le futur.
2

Créer un nouveau service worker dédié OneSignal

Créez OneSignalSDKWorker.js dans un sous-répertoire (p. ex., /push/onesignal/) contenant uniquement :
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Mettre à jour la configuration OneSignal

Définissez le nouveau chemin et la nouvelle portée en utilisant le tableau de bord ou OneSignal.init() comme décrit dans l’Étape 4 : Configurer le chemin du SDK.
4

Attendre que les abonnés migrent

Les nouveaux visiteurs et ceux qui reviennent s’enregistrent automatiquement avec le nouveau service worker. Attendez au moins un an pour que la majorité des abonnés existants revisitent votre site.
5

Nettoyage

Supprimez les utilisateurs inactifs plus anciens que votre période de rétention choisie, puis supprimez la ligne importScripts de OneSignal du fichier service worker original.
Option 2 : Changer le nom de fichier ou l’emplacement du fichierChanger le nom de fichier ou le répertoire est plus complexe car les navigateurs récupèrent le service worker depuis l’URL où il a été initialement enregistré. Les abonnés qui n’ont pas revisité votre site référencent toujours l’ancienne URL.
Vous devez continuer à héberger le fichier original à son ancienne URL pendant au moins un an. Le supprimer provoque des erreurs 404 lorsque le navigateur tente de mettre à jour le service worker, et les abonnés concernés cessent de recevoir des notifications.
Si votre fichier contient uniquement du code OneSignal
1

Ajouter un commentaire de rétention à l'ancien fichier

// KEEP until YYYY-MM-DD: Required for push delivery to subscribers still on the old service worker URL.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
2

Créer le nouveau fichier au nouvel emplacement

Placez OneSignalSDKWorker.js (ou votre nom de fichier choisi) dans le nouveau répertoire avec :
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Mettre à jour la configuration OneSignal

Définissez le nouveau chemin, nom de fichier et portée comme décrit dans l’Étape 4 : Configurer le chemin du SDK.
4

Attendre que les abonnés migrent

Les nouveaux visiteurs et ceux qui reviennent s’enregistrent avec le nouveau fichier automatiquement. Attendez au moins un an.
5

Nettoyage

Supprimez les utilisateurs inactifs plus anciens que votre période de rétention, puis supprimez l’ancien fichier.
Si votre fichier contient OneSignal + autre codeSuivez les étapes de l’Option 1 : Changer uniquement la portée ci-dessus. Le processus est identique.

​
Problèmes courants

​
Pourquoi mon service worker retourne-t-il un 404 ?

Le fichier n’est pas à l’URL attendue par le SDK. Accédez à l’URL complète du fichier dans votre navigateur pour confirmer qu’il est accessible. Si vous avez placé le fichier dans un sous-répertoire, vérifiez que serviceWorkerPath (code personnalisé) ou le paramètre de chemin du tableau de bord correspond à l’emplacement réel du fichier — incluant le répertoire et le nom de fichier.

​
Pourquoi les notifications ne s’affichent-elles plus après avoir déplacé le fichier service worker ?

Les abonnés existants référencent toujours l’ancienne URL du service worker. Le navigateur récupère l’URL enregistrée (mise en cache jusqu’à 24 heures) à chaque fois qu’un push arrive. Si l’ancienne URL retourne un 404, ces abonnés ne reçoivent pas les notifications. Continuez à héberger l’ancien fichier pendant au moins un an pendant que les abonnés migrent naturellement en revisitant votre site. Consultez le guide de migration et le guide Notifications push web non affichées.

​
Puis-je héberger le service worker sur un CDN ou un sous-domaine ?

Non. Les navigateurs exigent que les service workers soient servis depuis la même origine que la page qui les enregistre. Le fichier doit être sur votre domaine principal — pas un CDN, un sous-domaine ou un domaine différent.

​
Pourquoi ma PWA entre-t-elle en conflit avec le OneSignal service worker ?

Les deux sont probablement enregistrés à la portée racine (/) et un seul service worker peut être enregistré à une portée spécifique. Déplacez le OneSignal service worker vers une portée de sous-répertoire (p. ex., /push/onesignal/) pour que votre PWA conserve le contrôle de la portée racine, ou combinez les service workers comme décrit dans Combiner plusieurs service workers.

​
Puis-je renommer le fichier OneSignalSDKWorker.js ?

Oui. Si votre serveur nécessite une convention de nommage spécifique (p. ex., tout en minuscules), vous pouvez renommer le fichier en quelque chose comme onesignalsdkworker.js. Dans ce cas, mettez à jour le nom de fichier dans votre configuration OneSignal — soit le champ Service worker filename dans le tableau de bord, soit le paramètre serviceWorkerPath dans votre appel OneSignal.init(). Voir l’Étape 4 pour plus de détails.

​
Quel type de contenu mon serveur doit-il retourner pour le fichier service worker ?

Le serveur doit retourner Content-Type: application/javascript; charset=utf-8. Certaines configurations de serveur ou CDN peuvent retourner un type MIME incorrect, ce qui amène le navigateur à rejeter l’enregistrement du service worker.