Configurez le fichier OneSignalSDKWorker.js pour que votre site web puisse recevoir et afficher des notifications push web via OneSignal.
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.
Comment le OneSignal service worker traite les notifications push
Si vous utilisez le plugin WordPress, ignorez ce guide. Le plugin héberge OneSignalSDKWorker.js dans son répertoire sdk_files et configure le chemin pour vous. Ne téléversez pas le fichier à la racine de votre site et ne définissez pas de chemin personnalisé dans le tableau de bord ou dans le code. Consultez Configuration WordPress. Shopify déploie également le worker pour vous. Consultez Configuration Shopify.
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 seule ligne de code suivante :
Vous pouvez renommer le fichier si nécessaire (p. ex., onesignalsdkworker.js, ossw.js). Dans ce cas, remplacez 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 sert 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. Si vous utilisez une PWA, placez plutôt 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 la première étape :
Contenu attendu du fichier service worker dans le navigateur
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
Indiquer au SDK où trouver le fichier
Le Web SDK recherche OneSignalSDKWorker.js à la racine de votre site (https://yoursite.com/OneSignalSDKWorker.js) sauf si vous lui indiquez un emplacement différent. La façon de le lui indiquer dépend de votre type d’intégration.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, vous devez définir le chemin. Le Site typique le définit dans le tableau de bord. Le Code personnalisé le définit dans OneSignal.init(). Mélanger les deux ne fonctionne pas : les champs de chemin du tableau de bord ne s’appliquent pas au Code personnalisé, et serviceWorkerPath ne s’applique pas au Site typique.
Définissez le chemin dans le tableau de bord OneSignal. Ne passez pas serviceWorkerPath dans le code.
Allez dans Settings > Push & In-App > Web.
Sous Advanced Push Settings, activez Customize service worker paths and filenames.
Configuration du chemin du service worker dans le tableau de bord
Champ
Description
Exemple
Path to service worker files
Répertoire où est hébergé OneSignalSDKWorker.js.
/push/onesignal/
Service worker filename
Nom du fichier .js.
OneSignalSDKWorker.js
Service worker registration scope
Chemin 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.
Passez serviceWorkerPath et serviceWorkerParam dans votre appel OneSignal.init(). Le Code personnalisé n’utilise pas les champs Customize service worker paths and filenames du tableau de bord.
Chemin relatif depuis la racine du site vers le fichier .js (sans barre oblique initiale).
"push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scope
Chemin 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/"
Si le fichier n’est pas à la racine du site et que vous omettez ces options, le SDK récupère quand même https://yoursite.com/OneSignalSDKWorker.js et l’enregistrement échoue.Consultez la Configuration avec code personnalisé pour ajouter ces options à votre extrait init complet.
5
Vérifier les exigences du service worker
Le fichier OneSignalSDKWorker.js doit satisfaire toutes les exigences suivantes pour que les notifications push fonctionnent.
Exigence
Détails
Accessible publiquement
Accédez à l’URL du fichier dans un navigateur et confirmez que vous voyez le code JavaScript.
Type de contenu correct
Le serveur doit retourner Content-Type: application/javascript; charset=utf-8.
Même origine
Le 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.
HTTPS
Les 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.
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 :
Après la combinaison, mettez à jour la configuration OneSignal pour pointer vers votre fichier service worker existant. Suivez Indiquer au SDK où trouver le fichier en utilisant le chemin et le nom de fichier de votre fichier combiné.
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.
Quand et comment migrer votre service worker
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 :
Mettez à jour la portée en utilisant le tableau de bord (Site typique) ou serviceWorkerParam (Code personnalisé) comme décrit dans Indiquer au SDK où trouver le fichier. 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 au guide de 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 :
Définissez le nouveau chemin et la nouvelle portée en utilisant le tableau de bord (Site typique) ou OneSignal.init() (Code personnalisé) comme décrit dans Indiquer au SDK où trouver le fichier.
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 :
Non. Le plugin WordPress héberge et enregistre OneSignalSDKWorker.js dans son répertoire sdk_files. Ne téléversez pas de worker à la racine du site et ne définissez pas serviceWorkerPath dans le code. Consultez Configuration WordPress.
Comment définir le chemin du service worker pour le Site typique vs le Code personnalisé ?
Le Web SDK recherche OneSignalSDKWorker.js à la racine de votre site sauf si vous définissez un chemin personnalisé. Le Site typique définit ce chemin dans le tableau de bord sous Customize service worker paths and filenames. Le Code personnalisé le définit dans le code avec serviceWorkerPath et serviceWorkerParam dans OneSignal.init(). Les champs de chemin du tableau de bord ne s’appliquent pas au Code personnalisé. Consultez Indiquer au SDK où trouver le fichier.
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, le chemin configuré doit correspondre à l’emplacement réel du fichier, y compris le répertoire et le nom de fichier. Site typique : vérifiez les paramètres de chemin du tableau de bord. Code personnalisé : vérifiez serviceWorkerPath dans OneSignal.init().
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 actif à une portée donnée. 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 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), renommez le fichier en quelque chose comme onesignalsdkworker.js. Site typique : mettez à jour le champ Service worker filename dans le tableau de bord. Code personnalisé : mettez à jour serviceWorkerPath dans votre appel OneSignal.init(). Consultez Indiquer au SDK où trouver le fichier.
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 retournent un type MIME incorrect, ce qui amène le navigateur à rejeter l’enregistrement du service worker.
