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

> Configura el archivo OneSignalSDKWorker.js para que tu sitio web pueda recibir y mostrar notificaciones push web a través de OneSignal.

El OneSignal service worker (`OneSignalSDKWorker.js`) es un archivo JavaScript alojado en tu servidor que es necesario para las notificaciones push web. Permite que tu sitio reciba y muestre notificaciones, incluso cuando el usuario no está en tu página.

<Frame caption="Cómo el OneSignal service worker procesa las notificaciones 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 usas nuestro plugin de WordPress, el service worker se agrega automáticamente. Omite esta guía y vuelve a la [configuración de WordPress](./wordpress).
</Note>

## Configuración del service worker

Crea un archivo `OneSignalSDKWorker.js` dedicado para las notificaciones push de OneSignal. Si tu sitio ya tiene un service worker y quieres usar un solo archivo, consulta [Combinar múltiples service workers](#combining-multiple-service-workers) en su lugar.

<Steps>
  <Step title="Descargar o crear OneSignalSDKWorker.js">
    Descarga el archivo desde el dashboard de OneSignal durante la [configuración del Web SDK](./web-sdk-setup) o [desde GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).

    Alternativamente, crea un archivo llamado `OneSignalSDKWorker.js` con la siguiente línea de código:

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

    <Note>
      Puedes renombrar el archivo si es necesario (p. ej., `onesignalsdkworker.js`). Si lo haces, simplemente reemplaza `OneSignalSDKWorker.js` en esta guía con tu nombre de archivo.
    </Note>
  </Step>

  <Step title="Subir a tu servidor web">
    Coloca `OneSignalSDKWorker.js` en tu servidor para que sea accesible públicamente a través de HTTPS. El archivo no debe requerir autenticación o inicio de sesión para acceder.

    **Recomendado:** Aloja el archivo en un subdirectorio dedicado que nunca sirva páginas, como `/push/onesignal/`. Esto evita conflictos con otros service workers en tu sitio (p. ej., un service worker de PWA o AMP) y mantiene estable la ruta URL.

    * Ejemplo: `https://yoursite.com/push/onesignal/OneSignalSDKWorker.js`

    **Alternativa:** El OneSignal Web SDK busca por defecto el archivo en la raíz de tu sitio (`https://yoursite.com/OneSignalSDKWorker.js`). Puedes subir el archivo al directorio raíz, pero puede entrar en conflicto con otros service workers que necesiten alcance raíz. Por ejemplo, si usas una PWA, coloca `OneSignalSDKWorker.js` en un subdirectorio.

    <Warning>
      Elige una ruta URL **permanente**. Una vez que un navegador registra un service worker en una URL determinada, cambiar esa URL requiere una [migración](#migration-guide).
    </Warning>
  </Step>

  <Step title="Verificar que el archivo es accesible">
    Navega a la URL del archivo en tu navegador (p. ej., `https://yoursite.com/push/onesignal/OneSignalSDKWorker.js`).

    Deberías ver la línea `importScripts` del Paso 1:

    <Frame caption="Contenido esperado del archivo service worker en el navegador">
      <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 ves un error 404, una página en blanco o un mensaje de inicio de sesión, el archivo no está correctamente subido o está detrás de autenticación.
  </Step>

  <Step title="Configurar la ruta del SDK (solo subdirectorio)">
    Si colocaste el archivo en la raíz de tu sitio, no se necesita configuración adicional — salta al paso siguiente.

    Si colocaste el archivo en un subdirectorio, indica al SDK dónde encontrarlo:

    #### Configuración típica de sitio

    1. En el dashboard de OneSignal, ve a **Configuración > Push & In-App > Configuración web**.
    2. En **Configuración push avanzada**, habilita **Personalizar rutas y nombres de archivo del service worker**.

    <Frame caption="Configuración de la ruta del service worker en el dashboard">
      <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>

    | Campo                                 | Descripción                                                                                                                                                                   | Ejemplo                 |
    | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
    | **Path to service worker files**      | Directorio donde está alojado `OneSignalSDKWorker.js`.                                                                                                                        | `/push/onesignal/`      |
    | **Service worker filename**           | Nombre del archivo `.js`.                                                                                                                                                     | `OneSignalSDKWorker.js` |
    | **Service worker registration scope** | Ruta URL que controla el service worker. Debe estar en o por debajo del directorio donde está alojado el archivo. Usa una ruta que nunca sirva páginas orientadas al usuario. | `/push/onesignal/`      |

    #### Configuración de código personalizado

    Pasa `serviceWorkerPath` y `serviceWorkerParam` en tu llamada a [`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>
    ```

    | Parámetro                  | Descripción                                                                                                                                                                   | Ejemplo                                  |
    | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
    | `serviceWorkerPath`        | Ruta relativa desde la raíz del sitio hasta el archivo `.js` (sin barra diagonal inicial).                                                                                    | `"push/onesignal/OneSignalSDKWorker.js"` |
    | `serviceWorkerParam.scope` | Ruta URL que controla el service worker. Debe estar en o por debajo del directorio donde está alojado el archivo. Usa una ruta que nunca sirva páginas orientadas al usuario. | `"/push/onesignal/"`                     |
  </Step>

  <Step title="Revisar los requisitos del service worker">
    El archivo `OneSignalSDKWorker.js` debe cumplir todos los siguientes requisitos. Si alguno no se cumple, las notificaciones push no funcionarán.

    | Requisito                      | Detalles                                                                                                                                                                                                                                                        |
    | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Accesible públicamente**     | Navega a la URL del archivo en un navegador y confirma que puedes ver el código JavaScript.                                                                                                                                                                     |
    | **Tipo de contenido correcto** | El servidor debe devolver `Content-Type: application/javascript; charset=utf-8`.                                                                                                                                                                                |
    | **Mismo origen**               | El archivo debe estar alojado en el mismo dominio que tu sitio. No se permiten CDNs ni subdominios. Consulta [MDN: Registering your worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker). |
    | **HTTPS**                      | Los service workers requieren un contexto seguro. `localhost` es la única excepción durante el desarrollo.                                                                                                                                                      |

    <Check>
      La configuración del service worker está completa.
    </Check>

    <Card title="Configuración del Web SDK" icon="browsers" href="./web-sdk-setup">
      Continúa con la guía de configuración del Web SDK para los próximos pasos.
    </Card>
  </Step>
</Steps>

***

## Combinar múltiples service workers

Cada archivo service worker en tu sitio se registra en un **alcance** — una ruta URL que determina qué páginas controla. Solo un service worker puede estar activo en un alcance dado. Si ya tienes un service worker (por ejemplo, una PWA o un worker de caché) y quieres que OneSignal comparta el mismo archivo, puedes combinarlos.

<Warning>
  Mantener los service workers en archivos separados con alcances separados es más fácil de mantener y evita conflictos. Solo combínalos si tu configuración requiere un único archivo service worker.
</Warning>

Para combinar, añade la línea `importScripts` de OneSignal a tu archivo service worker **existente**:

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

Después de combinar, actualiza la configuración de OneSignal para que apunte a tu archivo service worker existente. Sigue el [Paso 4: Configurar la ruta del SDK](#step-4-configure-the-sdk-path-subdirectory-only) usando la ruta y el nombre de archivo de tu archivo combinado.

***

## Guía de migración

Esta sección es para clientes existentes de OneSignal que necesitan cambiar la ruta del archivo service worker, el nombre de archivo o el alcance. No sigas estos pasos a menos que tengas una razón específica para cambiar tu configuración actual.

<Accordion title="Cuándo y cómo migrar tu service worker">
  **Razones para migrar:**

  * El OneSignal service worker con alcance raíz entra en conflicto con una Progressive Web App (PWA)
  * El service worker entra en conflicto con AMP u otro service worker de caché
  * Las políticas de seguridad prohíben el código de service worker de terceros en el alcance raíz

  **Opción 1: Cambiar solo el alcance (recomendado)**

  Cambiar solo el alcance es la migración más segura. El archivo permanece en su URL actual, por lo que los suscriptores existentes continúan recibiendo notificaciones sin interrupciones.

  **Si tu archivo contiene solo código de OneSignal**

  Confirma que `OneSignalSDKWorker.js` contiene únicamente:

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

  Actualiza el alcance usando el dashboard o `serviceWorkerParam` como se describe en el [Paso 4: Configurar la ruta del SDK](#step-4-configure-the-sdk-path-subdirectory-only). No se necesitan otros cambios.

  <Warning>
    Si `OneSignalSDKWorker.js` **no** está alojado en la raíz de tu dominio hoy, debes continuar alojándolo en su URL actual con el encabezado `Service-Worker-Allowed` durante al menos un año. Añade un comentario en tu código backend o documentación interna para que el archivo no se elimine accidentalmente.
  </Warning>

  **Si tu archivo contiene OneSignal + otro código**

  Tu service worker puede incluir llamadas `importScripts` adicionales (p. ej., al seguir la guía [Combinar múltiples service workers](#combining-multiple-service-workers)). Si tu configuración actual sigue funcionando, **mantenla como está** — separar un service worker fusionado requiere un despliegue en dos fases.

  Si debes separarlos:

  <Steps>
    <Step title="Añadir un comentario de retención al archivo existente">
      Encima de la línea `importScripts` de OneSignal en tu service worker actual, añade:

      ```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");
      ```

      Establece la fecha al menos **un año** en el futuro.
    </Step>

    <Step title="Crear un nuevo service worker dedicado de OneSignal">
      Crea `OneSignalSDKWorker.js` en un subdirectorio (p. ej., `/push/onesignal/`) que contenga solo:

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

    <Step title="Actualizar la configuración de OneSignal">
      Establece la nueva ruta y alcance usando el dashboard o `OneSignal.init()` como se describe en el [Paso 4: Configurar la ruta del SDK](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="Esperar a que los suscriptores migren">
      Los visitantes nuevos y los que regresan se registran automáticamente con el nuevo service worker. Espera al menos un año para que la mayoría de los suscriptores existentes vuelvan a visitar tu sitio.
    </Step>

    <Step title="Limpieza">
      [Elimina los usuarios inactivos](./delete-users) más antiguos que el período de retención elegido, luego elimina la línea `importScripts` de OneSignal del archivo service worker original.
    </Step>
  </Steps>

  **Opción 2: Cambiar el nombre de archivo o la ubicación del archivo**

  Cambiar el nombre de archivo o el directorio es más complejo porque los navegadores obtienen el service worker desde la URL donde fue originalmente registrado. Los suscriptores que no han vuelto a visitar tu sitio siguen referenciando la URL antigua.

  <Warning>
    Debes continuar alojando el archivo original en su URL antigua durante al menos un año. Eliminarlo causa errores 404 cuando el navegador intenta actualizar el service worker, y los suscriptores afectados dejan de recibir notificaciones.
  </Warning>

  **Si tu archivo contiene solo código de OneSignal**

  <Steps>
    <Step title="Añadir un comentario de retención al archivo antiguo">
      ```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="Crear el nuevo archivo en la nueva ubicación">
      Coloca `OneSignalSDKWorker.js` (o tu nombre de archivo elegido) en el nuevo directorio con:

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

    <Step title="Actualizar la configuración de OneSignal">
      Establece la nueva ruta, nombre de archivo y alcance como se describe en el [Paso 4: Configurar la ruta del SDK](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="Esperar a que los suscriptores migren">
      Los visitantes nuevos y los que regresan se registran con el nuevo archivo automáticamente. Espera al menos un año.
    </Step>

    <Step title="Limpieza">
      [Elimina los usuarios inactivos](./delete-users) más antiguos que tu período de retención, luego elimina el archivo antiguo.
    </Step>
  </Steps>

  **Si tu archivo contiene OneSignal + otro código**

  Sigue los pasos de la **Opción 1: Cambiar solo el alcance** anterior. El proceso es el mismo.
</Accordion>

***

## Problemas comunes

### ¿Por qué mi service worker devuelve un 404?

El archivo no está en la URL que espera el SDK. Navega a la URL completa del archivo en tu navegador para confirmar que es accesible. Si colocaste el archivo en un subdirectorio, verifica que `serviceWorkerPath` (código personalizado) o la configuración de ruta del dashboard coincida con la ubicación real del archivo — incluido el directorio y el nombre de archivo.

### ¿Por qué las notificaciones no se muestran después de mover el archivo service worker?

Los suscriptores existentes siguen referenciando la URL del service worker anterior. El navegador obtiene la URL registrada (en caché hasta 24 horas) cada vez que llega un push. Si la URL antigua devuelve un 404, esos suscriptores no reciben notificaciones. Continúa alojando el archivo antiguo durante al menos un año mientras los suscriptores migran naturalmente al volver a visitar tu sitio. Consulta la [guía de migración](#migration-guide) y la guía [Notificaciones push web no se muestran](./notifications-not-shown-web-push).

### ¿Puedo alojar el service worker en un CDN o subdominio?

No. Los navegadores requieren que los service workers se sirvan desde el mismo origen que la página que los registra. El archivo debe estar en tu dominio principal — no en un CDN, subdominio o dominio diferente.

### ¿Por qué mi PWA entra en conflicto con el OneSignal service worker?

Probablemente ambos están registrados en el alcance raíz (`/`) y solo un service worker puede estar registrado en un alcance específico. Mueve el OneSignal service worker a un alcance de subdirectorio (p. ej., `/push/onesignal/`) para que tu PWA retenga el control del alcance raíz, o combina los service workers como se describe en [Combinar múltiples service workers](#combining-multiple-service-workers).

### ¿Puedo renombrar el archivo OneSignalSDKWorker.js?

Sí. Si tu servidor requiere una convención de nombres específica (p. ej., todo en minúsculas), puedes renombrar el archivo a algo como `onesignalsdkworker.js`. Si lo haces, actualiza el nombre de archivo en tu configuración de OneSignal — ya sea el campo **Service worker filename** en el dashboard o el parámetro `serviceWorkerPath` en tu llamada a `OneSignal.init()`. Consulta el [Paso 4](#step-4-configure-the-sdk-path-subdirectory-only) para más detalles.

### ¿Qué tipo de contenido debe devolver mi servidor para el archivo service worker?

El servidor debe devolver `Content-Type: application/javascript; charset=utf-8`. Algunas configuraciones de servidor o CDN pueden devolver un tipo MIME incorrecto, lo que hace que el navegador rechace el registro del service worker.