Configura el archivo OneSignalSDKWorker.js para que tu sitio web pueda recibir y mostrar notificaciones web push 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 web push. 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 el plugin de WordPress, omite esta guía. El plugin aloja OneSignalSDKWorker.js en su directorio sdk_files y configura la ruta por ti. No subas el archivo a la raíz de tu sitio ni establezcas una ruta personalizada en el dashboard o en código. Consulta Configuración WordPress. Shopify también despliega el worker por ti. Consulta Configuración Shopify.
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 SDK Web o desde GitHub.Alternativamente, crea un archivo llamado OneSignalSDKWorker.js con la siguiente única línea de código:
Puedes renombrar el archivo si es necesario (p. ej., onesignalsdkworker.js, ossw.js). Si lo haces, 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. 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 primer paso:
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
Indicar al SDK dónde encontrar el archivo
El Web SDK busca OneSignalSDKWorker.js en la raíz de tu sitio (https://yoursite.com/OneSignalSDKWorker.js) a menos que le indiques una ubicación diferente. Cómo se lo indicas depende de tu tipo de integración.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, debes establecer la ruta. Sitio típico la establece en el dashboard. Código personalizado la establece en OneSignal.init(). Mezclar los dos no funciona: los campos de ruta del dashboard no aplican a Código personalizado, y serviceWorkerPath no aplica a Sitio típico.
Establece la ruta en el dashboard de OneSignal. No pases serviceWorkerPath en código.
Ve a Settings > Push & In-App > Web.
Bajo Advanced Push Settings, habilita Customize service worker paths and filenames.
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.
Pasa serviceWorkerPath y serviceWorkerParam en tu llamada a OneSignal.init(). Código personalizado no usa los campos Customize service worker paths and filenames del dashboard.
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/"
Si el archivo no está en la raíz del sitio y omites estas opciones, el SDK igualmente busca https://yoursite.com/OneSignalSDKWorker.js y el registro falla.Consulta Configuración con código personalizado para agregar estas opciones a tu snippet de inicialización completo.
5
Revisar los requisitos del service worker
El archivo OneSignalSDKWorker.js debe cumplir todos los siguientes requisitos para que las notificaciones push funcionen.
Requisito
Detalles
Accesible públicamente
Navega a la URL del archivo en un navegador y confirma que ves 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 CDN 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 SDK Web
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 Indicar al SDK dónde encontrar el archivo 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 (Sitio típico) o serviceWorkerParam (Código personalizado) como se describe en Indicar al SDK dónde encontrar el archivo. 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:
Establece la nueva ruta y alcance usando el dashboard (Sitio típico) o OneSignal.init() (Código personalizado) como se describe en Indicar al SDK dónde encontrar el archivo.
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:
No. El plugin de WordPress aloja y registra OneSignalSDKWorker.js en su directorio sdk_files. No subas un worker a la raíz del sitio ni establezcas serviceWorkerPath en código. Consulta Configuración WordPress.
¿Cómo establezco la ruta del service worker para Sitio típico vs Código personalizado?
El Web SDK busca OneSignalSDKWorker.js en la raíz de tu sitio a menos que establezcas una ruta personalizada. Sitio típico establece esa ruta en el dashboard bajo Customize service worker paths and filenames. Código personalizado la establece en código con serviceWorkerPath y serviceWorkerParam en OneSignal.init(). Los campos de ruta del dashboard no aplican a Código personalizado. Consulta Indicar al SDK dónde encontrar el archivo.
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, la ruta configurada debe coincidir con la ubicación real del archivo, incluido el directorio y el nombre de archivo. Sitio típico: verifica la configuración de ruta del dashboard. Código personalizado: verifica serviceWorkerPath en OneSignal.init().
¿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 web push no mostradas.
¿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 activo en un alcance dado. 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 combínalos 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), renombra el archivo a algo como onesignalsdkworker.js. Sitio típico: actualiza el campo Service worker filename en el dashboard. Código personalizado: actualiza serviceWorkerPath en tu llamada a OneSignal.init(). Consulta Indicar al SDK dónde encontrar el archivo.
¿Qué tipo de contenido debe devolver mi servidor para el archivo service worker?
El servidor debe devolver Content-Type: application/javascript; charset=utf-8. Algunos servidores o configuraciones de CDN devuelven un tipo MIME incorrecto, lo que hace que el navegador rechace el registro del service worker.
¿Esta página le ayudó?
Assistant
Responses are generated using AI and may contain mistakes.
