> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal service worker

> 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.

<Frame caption="Comment le OneSignal service worker traite les notifications push">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/67882a5-onesignsal-service-worker.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=e0b50cfe6ccc36c1b2b6d36219b6e3ad" alt="Diagram showing the OneSignal service worker receiving a push event and displaying a notification" width="2016" height="949" data-path="images/docs/67882a5-onesignsal-service-worker.jpg" />
</Frame>

<Note>
  Si vous utilisez notre plugin WordPress, le service worker est ajouté automatiquement. Ignorez ce guide et revenez à la [configuration WordPress](./wordpress).
</Note>

## 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](#combining-multiple-service-workers).

<Steps>
  <Step title="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](./web-sdk-setup) ou [depuis GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).

    Vous pouvez également créer un fichier nommé `OneSignalSDKWorker.js` avec la ligne de code suivante :

    ```javascript theme={null}
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    <Warning>
      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](#migration-guide).
    </Warning>
  </Step>

  <Step title="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 :

    <Frame caption="Contenu attendu du fichier service worker dans le navigateur">
      <img src="https://mintcdn.com/onesignal/eSOC1PsvyAo3Gten/images/push/service-worker-code-example.png?fit=max&auto=format&n=eSOC1PsvyAo3Gten&q=85&s=3add122d37c9f12a39f1d7e3d40eeaba" alt="Browser displaying the single importScripts line inside OneSignalSDKWorker.js" width="1678" height="322" data-path="images/push/service-worker-code-example.png" />
    </Frame>

    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.
  </Step>

  <Step title="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**.

    <Frame caption="Configuration du chemin du service worker dans le tableau de bord">
      <img src="https://mintcdn.com/onesignal/npQH4TNAoIbyiAie/images/dashboard/service-worker-configuration-typical-site-setup.png?fit=max&auto=format&n=npQH4TNAoIbyiAie&q=85&s=0bc69998eea5273d287af408c6e925b3" alt="OneSignal dashboard fields for service worker path, filename, and registration scope" width="1840" height="794" data-path="images/dashboard/service-worker-configuration-typical-site-setup.png" />
    </Frame>

    | 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. | `/push/onesignal/`      |

    #### Configuration de code personnalisé

    Passez `serviceWorkerPath` et `serviceWorkerParam` dans votre appel [`OneSignal.init()`](./web-push-custom-code-setup) :

    ```html theme={null}
    <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ètre                  | Description                                                                                                                                                                                 | Exemple                                  |
    | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
    | `serviceWorkerPath`        | 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/"`                     |
  </Step>

  <Step title="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.

    | 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://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker). |
    | **HTTPS**                   | Les service workers nécessitent un contexte sécurisé. `localhost` est la seule exception pendant le développement.                                                                                                                                                               |

    <Check>
      La configuration du service worker est terminée.
    </Check>

    <Card title="Configuration du SDK Web" icon="browsers" href="./web-sdk-setup">
      Continuez avec le guide de configuration du SDK Web pour les prochaines étapes.
    </Card>
  </Step>
</Steps>

***

## 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.

<Warning>
  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.
</Warning>

Pour combiner, ajoutez la ligne `importScripts` de OneSignal à votre fichier service worker **existant** :

```javascript theme={null}
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](#step-4-configure-the-sdk-path-subdirectory-only) 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.

<Accordion title="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 OneSignal**

  Confirmez que `OneSignalSDKWorker.js` contient uniquement :

  ```javascript theme={null}
  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](#step-4-configure-the-sdk-path-subdirectory-only). Aucune autre modification n'est nécessaire.

  <Warning>
    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é.
  </Warning>

  **Si votre fichier contient OneSignal + autre code**

  Votre service worker peut inclure des appels `importScripts` supplémentaires (p. ex., suite à la [combinaison de plusieurs service workers](#combining-multiple-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 :

  <Steps>
    <Step title="Ajouter un commentaire de rétention au fichier existant">
      Au-dessus de la ligne `importScripts` de OneSignal dans votre service worker actuel, ajoutez :

      ```javascript theme={null}
      // 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.
    </Step>

    <Step title="Créer un nouveau service worker dédié OneSignal">
      Créez `OneSignalSDKWorker.js` dans un sous-répertoire (p. ex., `/push/onesignal/`) contenant uniquement :

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="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](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="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.
    </Step>

    <Step title="Nettoyage">
      [Supprimez les utilisateurs inactifs](./delete-users) plus anciens que votre période de rétention choisie, puis supprimez la ligne `importScripts` de OneSignal du fichier service worker original.
    </Step>
  </Steps>

  **Option 2 : Changer le nom de fichier ou l'emplacement du fichier**

  Changer 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.

  <Warning>
    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.
  </Warning>

  **Si votre fichier contient uniquement du code OneSignal**

  <Steps>
    <Step title="Ajouter un commentaire de rétention à l'ancien fichier">
      ```javascript theme={null}
      // 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");
      ```
    </Step>

    <Step title="Créer le nouveau fichier au nouvel emplacement">
      Placez `OneSignalSDKWorker.js` (ou votre nom de fichier choisi) dans le nouveau répertoire avec :

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="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](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="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.
    </Step>

    <Step title="Nettoyage">
      [Supprimez les utilisateurs inactifs](./delete-users) plus anciens que votre période de rétention, puis supprimez l'ancien fichier.
    </Step>
  </Steps>

  **Si votre fichier contient OneSignal + autre code**

  Suivez les étapes de l'**Option 1 : Changer uniquement la portée** ci-dessus. Le processus est identique.
</Accordion>

***

## 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](#migration-guide) et le guide [Notifications push web non affichées](./notifications-not-shown-web-push).

### 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](#combining-multiple-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](#step-4-configure-the-sdk-path-subdirectory-only) 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.