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.
Cómo el OneSignal service worker procesa las notificaciones push
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.
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:
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.
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:
Contenido esperado del archivo service worker en el navegador
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:
En el dashboard de OneSignal, ve a Configuración > Push & In-App > Configuración web.
En Configuración push avanzada, habilita Personalizar rutas y nombres de archivo del service worker.
Configuración de la ruta del service worker en el dashboard
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.
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/"
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.
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
Los 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.
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:
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.
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.
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 OneSignalConfirma que OneSignalSDKWorker.js contiene únicamente:
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.jsno 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:
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:
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.
