Saltar al contenido principal

​
Resumen

Esta guía cubre cómo configurar el OneSignal Service Worker para Notificaciones Web Push.
Si estás usando nuestro plugin de WordPress, el archivo OneSignal Service Worker se agrega automáticamente y no deberías agregar estos archivos a tu sitio manualmente. Regresa a WordPress setup para más información.

​
¿Qué son los service workers?

Un Service Worker es un script en segundo plano que se ejecuta en un hilo separado de la página principal. Habilita funciones como notificaciones push, almacenamiento en caché sin conexión y sincronización en segundo plano. Se instala cuando tu sitio lo registra y, aunque no siempre está ejecutándose, puede activarse para manejar eventos (incluido push) incluso después de que el usuario navegue fuera.

Cómo funcionan los service workers

​
Cómo integrar el service worker de OneSignal

A medida que sigas nuestra guía de Web SDK Setup, se te proporcionará el archivo de service worker OneSignalSDKWorker.js.

​
Descargar el archivo .js

Descarga el archivo OneSignalSDKWorker.js del dashboard de OneSignal o Descarga el Archivo de Service Worker de OneSignal aquí.

​
Subir el archivo .js a tu servidor

Nuestro SDK busca por defecto en la raíz de tu sitio el archivo OneSignalSDKWorker.js, por ejemplo: https://yoursite.com/OneSignalSDKWorker.js Simplemente puedes subir este archivo al directorio raíz de tu sitio y regresar a la guía de Web push setup para los siguientes pasos. Sin embargo, se recomienda colocar este archivo OneSignalSDKWorker.js en una ruta de subdirectorio a la que nunca enlazarás usuarios como https://yoursite.com/push/onesignal/OneSignalSDKWorker.js. Puedes colocar este archivo en la raíz, pero puede entrar en conflicto con otros Service Workers que tengas ahora o que puedas agregar en el futuro. Además, el archivo debe colocarse en una ruta de ubicación permanente que nunca cambiará. Una vez que un Service Worker esté registrado con el navegador, es difícil cambiarlo.

​
Configuración del Service Worker

El archivo de service worker de OneSignal OneSignalSDKWorker.js debe cumplir estos requisitos:
  • El archivo debe ser públicamente accesible, lo que significa que deberías poder navegar al archivo en un navegador y ver el código.
  • El archivo debe servirse con un content-type de application/javascript; charset=utf-8.
  • El archivo debe apuntar al mismo origen del sitio (tu dominio del sitio). Apuntar a un Service Worker en un origen diferente no está permitido. No CDNs ni subdominios.

​
Confirmar que el service worker está configurado correctamente

Visita el service worker en tu navegador. Deberías ver el código del service worker: importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Ejemplo del código del service worker

Si subiste el archivo OneSignalSDKWorker.js a la raíz de tu sitio (es accesible en https://yoursite.com/OneSignalSDKWorker.js) entonces no se necesita ninguna acción adicional. Sin embargo, si lo pusiste en un subdirectorio como https://yoursite.com/push/onesignal/OneSignalSDKWorker.js entonces necesitarás establecer el alcance de registro de la siguiente manera:
  • Configuración típica de sitio
  • Configuración de código personalizado
En el dashboard de OneSignal, ve a Settings > Push & In-App > Web Settings de tu AppBajo Advanced Push Settings, activa el interruptor Customize service workers paths and filenames e ingresa tus datos.

Configuración del service worker para configuración típica de sitio

  • Path to service worker files es el directorio donde estará disponible el archivo OneSignal Service Worker. Si el Service Worker está disponible en: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js entonces la ruta es: /push/onesignal/
  • Main and Updater service worker filenames es el nombre del archivo Service worker. Debería ser OneSignalSDKWorker.js pero si lo cambiaste, asegúrate de usar la extensión de archivo .js. Por ejemplo, si tu servidor fuerza archivos a minúsculas, puedes establecer el nombre de archivo como onesignalsdkworker.js
  • Service worker registration scope son las páginas en las que este archivo puede funcionar. Debe ser una ruta a la que nunca enlazarás usuarios y nunca alojarás ninguna página desde ahora o en el futuro. Un ejemplo de ruta común: /push/onesignal/ y el alcance podría ser la misma ruta o más profundo como: /push/onesignal/js/
¡La configuración del service worker está completa!Regresa a la guía Web SDK Setup para los siguientes pasos.

​
Guía de migración del OneSignal Service Worker

Esta sección es solo para clientes que ya usan OneSignal, tienen una gran cantidad de suscriptores de web push, y quieren cambiar la configuración del OneSignal Service Worker. Esto no se recomienda a menos que tengas una razón específica para hacerlo.
Esta guía es solo para clientes que ya usan OneSignal en su sitio web actualmente y quieren mover el archivo OneSignalSDKWorker.js a una ruta o alcance diferente.
El Service Worker de OneSignal tiene como alcance predeterminado la raíz, lo que puede crear los siguientes problemas para tu sitio:
  • Conflicto con una PWA
  • Conflicto con una configuración AMP
  • Conflicto con tu Service Worker de almacenamiento en caché, o cualquier otra función de Service Worker que requiera alcance raíz
  • Tu sitio tiene requisitos de seguridad que no permiten que código de Service Worker de terceros se ejecute en un alcance que controla una página que tus usuarios visitarán.
Si uno o más se aplican a ti, por favor sigue esta guía.

​
Elegir un Alcance de Service Worker de OneSignal

Se recomienda que elijas una ruta de alcance de Service Worker a la que nunca enlazarás a un usuario, pero que aún sea claro lo que hace. Ejemplo: /push/onesignal/. De esta manera tu PWA, AMP, o cualquier otro ServiceWorker de almacenamiento en caché puede controlar la página que ve un usuario para funcionar correctamente.Está bien poner múltiples service workers en la misma ruta de ubicación, pero DEBEN tener ruta de alcance única.
  • Opción 1: Cambiar alcance
  • Opción 2: Cambiar nombre de archivo o ubicación

​
Cambiar de manera segura el Alcance del Service Worker de OneSignal

Se recomienda solo cambiar el alcance si es posible, cambiar el nombre de archivo o ruta de ubicación del Service Worker mismo tiene consideraciones adicionales. Presta mucha atención tanto a los detalles de qué escenario se aplica a ti como a cada paso para asegurarte de no perder suscriptores ni tener problemas de visualización de notificaciones

​
Tipo de Configuración 1. Configuración Predeterminada de OneSignal - Alcance raíz ”/” Y Contenido predeterminado de OneSignalSDKWorker.js

Confirma que el contenido de tu archivo OneSignalSDKWorker.js sea el mismo que se encuentra en Descarga el Archivo de Service Worker de OneSignal aquí. (Sin ningún otro código no relacionado con OneSignal que puedas necesitar)En este caso puedes cambiar el alcance de OneSignal a cualquier cosa que elijas para hacer espacio para que otro Service Worker sea colocado en el alcance raíz. Consulta arriba Personaliza tu Integración de Service Worker.
Si tu OneSignalSDKWorker.js NO está alojado en la raíz de tu dominio hoy, por ejemplo NO lo tienes alojado así: https://mysite.com/OneSignalSDKWorker.js entonces DEBES seguir alojándolo con el encabezado Service-Worker-Allowed por un período de tiempo extendido. (Se recomienda 1 año o más)Si es posible, recomendamos agregar un comentario en tu código backend o tu documentación interna para asegurar que no se elimine accidentalmente.

​
Tipo de Configuración 2. Poco Común - Alcance raíz ”/” Y OneSignalSDKWorker.js (o tu nombre de archivo configurado) contiene OneSignal + otro código o importScripts

Esto es menos común pero es posible que ya hayas hecho esto siguiendo esta guía de OneSignal “Integrar Múltiples Service Workers”. Si esta configuración aún cumple todos tus requisitos, se recomienda encarecidamente mantener tu configuración tal como está debido a la implementación compleja de dos fases requerida para separar el archivo ServiceWorker fusionado que maneja eventos push.
Esta sección se aplica si tienes OneSignal Y algún otro código personalizado o importScript como el siguiente en tu Service Worker actual.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//And some other site specific code in the same file example.
importScripts("https://site.com/my-other-service-worker.js");
1

Mantén tu código de service worker existente.

Agrega un comentario de código a tu archivo ServiceWorker existente sobre esta línea importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); para mantenerlo por un período de tiempo extendido. (se recomienda un año o más, depende de cuánto tiempo quieras seguir enviando pushes a usuarios que nunca vuelven a visitar tu sitio). Ejemplo: // MANTENER Hasta YYYY-MM-DD: Requerido para que los pushes funcionen correctamente para usuarios que no han vuelto a visitar para migrar al nuevo ServiceWorker específico de OneSignal.
2

Crear un nuevo archivo de service worker

Crea un nuevo OneSignalSDKWorker.js bajo un directorio diferente, como /push/onesignal/ con la siguiente línea única de código importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Sigue la guía sobre "Personalizar tu Integración de Service Worker" para cambiar tu alcance, nombre de archivo y ruta.

4

En este punto, los usuarios nuevos y que regresan se suscribirán automáticamente al nuevo ServiceWorker de OneSignal.

5

Espera la cantidad de tiempo (un año aproximadamente) como se indica en el paso 1.

6

Sigue la guía de OneSignal - Eliminar Usuarios para eliminar usuarios más antiguos que la línea de tiempo que elegiste.

7

Eliminar comentario del service worker original

Finalmente, elimina la línea importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); con el comentario de tu ServiceWorker raíz original.

​
Migrar alcance del ServiceWorker de OneSignal - FAQ

¿Por qué debo seguir alojando la URL del archivo ServiceWorker original si cambio el nombre o la ruta de ubicación?
Esto es necesario para aquellos usuarios que no han vuelto a visitar tu sitio para que se recoja el nuevo nombre de archivo. El archivo ServiceWorker original será buscado por el navegador cada vez que envíes un push (si ha pasado el tiempo de expiración de caché, el máximo de caché es de 24 horas). Verás un aumento en errores 404 devueltos de tu proveedor de hosting al enviar un push si el archivo ServiceWorker original no está disponible. Esto puede resultar en más solicitudes a tu servidor. Esto también significa que esos usuarios no recibirán las nuevas funciones y correcciones de OneSignal.