Saltar al contenido principal

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.

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.
Diagram showing the OneSignal service worker receiving a push event and displaying a notification
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.

​
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 en su lugar.
1

Descargar o crear OneSignalSDKWorker.js

Descarga el archivo desde el dashboard de OneSignal durante la configuración del Web SDK o desde GitHub.Alternativamente, crea un archivo llamado OneSignalSDKWorker.js con la siguiente línea de código:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
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.
2

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

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:
Browser displaying the single importScripts line inside OneSignalSDKWorker.js
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.
4

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.
OneSignal dashboard fields for service worker path, filename, and registration scope
CampoDescripciónEjemplo
Path to service worker filesDirectorio donde está alojado OneSignalSDKWorker.js./push/onesignal/
Service worker filenameNombre del archivo .js.OneSignalSDKWorker.js
Service worker registration scopeRuta 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():
<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ámetroDescripciónEjemplo
serviceWorkerPathRuta relativa desde la raíz del sitio hasta el archivo .js (sin barra diagonal inicial)."push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scopeRuta 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/"
5

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.
RequisitoDetalles
Accesible públicamenteNavega a la URL del archivo en un navegador y confirma que puedes ver el código JavaScript.
Tipo de contenido correctoEl servidor debe devolver Content-Type: application/javascript; charset=utf-8.
Mismo origenEl archivo debe estar alojado en el mismo dominio que tu sitio. No se permiten CDNs ni subdominios. Consulta MDN: Registering your worker.
HTTPSLos service workers requieren un contexto seguro. localhost es la única excepción durante el desarrollo.
La configuración del service worker está completa.

Configuración del Web SDK

Continúa con la guía de configuración del Web SDK para los próximos pasos.

​
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.
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.
Para combinar, añade la línea importScripts de OneSignal a tu archivo service worker existente: 
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 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.
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 OneSignalConfirma que OneSignalSDKWorker.js contiene únicamente:
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. No se necesitan otros cambios.
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.
Si tu archivo contiene OneSignal + otro códigoTu service worker puede incluir llamadas importScripts adicionales (p. ej., al seguir la guía Combinar múltiples 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:
1

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:
// 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.
2

Crear un nuevo service worker dedicado de OneSignal

Crea OneSignalSDKWorker.js en un subdirectorio (p. ej., /push/onesignal/) que contenga solo:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

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

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

Limpieza

Elimina los usuarios inactivos más antiguos que el período de retención elegido, luego elimina la línea importScripts de OneSignal del archivo service worker original.
Opción 2: Cambiar el nombre de archivo o la ubicación del archivoCambiar 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.
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.
Si tu archivo contiene solo código de OneSignal
1

Añadir un comentario de retención al archivo antiguo

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

Crear el nuevo archivo en la nueva ubicación

Coloca OneSignalSDKWorker.js (o tu nombre de archivo elegido) en el nuevo directorio con:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

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

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

Limpieza

Elimina los usuarios inactivos más antiguos que tu período de retención, luego elimina el archivo antiguo.
Si tu archivo contiene OneSignal + otro códigoSigue los pasos de la Opción 1: Cambiar solo el alcance anterior. El proceso es el mismo.

​
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 y la guía Notificaciones push web no se muestran.

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

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