Configuración de push web con código personalizado

Solo usa esta configuración con código personalizado si necesitas configuración avanzada o control programático. Para la mayoría de usuarios, recomendamos:

Si estás usando un framework JavaScript, sigue estas guías especializadas:

Requisitos

Sitio web HTTPS: El push web no funciona en HTTP ni en modos de navegación incógnito/privada.
Acceso al servidor: Necesitarás subir un archivo service worker a tu sitio.
Origen único: El push web sigue la política de mismo origen. Si tienes múltiples orígenes (dominios/subdominios), necesitarás múltiples aplicaciones OneSignal (una por origen). Para cumplir con esta limitación del navegador, puedes:
- Redirigir el tráfico a un único origen para las suscripciones.
- Crear múltiples aplicaciones OneSignal, una por origen.

Configurar tu aplicación y plataforma OneSignal

En el panel de OneSignal:

Ve a Settings > Push & In-App > Web.
Selecciona el tipo de integración Custom Code.

Configuración del sitio

Agrega los detalles del sitio:

Site Name: El nombre de tu sitio y el título de notificación predeterminado.
Site URL: El origen exacto de tu sitio, por ejemplo https://yourdomain.com. Evita usar www. si tu sitio no está configurado así. Consulta los Requisitos si tienes múltiples orígenes.
Auto Resubscribe: Habilita esto para resuscribir automáticamente a los usuarios que borren sus datos del navegador cuando regresen a tu sitio (sin necesidad de una nueva solicitud de permiso).
Default Icon URL: Sube un PNG, JPG o GIF no animado cuadrado de 256×256 que aparece en notificaciones y prompts. Si no se configura, se usa un ícono de campana como predeterminado. Consulta Iconos de notificación.

Si los usuarios borran los datos de su navegador, dejan de recibir push hasta que regresen. Habilita Auto Resubscribe para que se suscriban de nuevo sin una nueva solicitud de permiso. Consulta Suscripciones.

OneSignal web push configuration showing site name, URL, and icon settings — Configuración web en el panel de OneSignal

Pruebas locales

Para probar en localhost, usa una aplicación OneSignal separada de tu aplicación de producción y agrega allowLocalhostAsSecureOrigin: true a tus opciones de init. Si estás probando localhost en HTTPS con un certificado autofirmado, puede que necesites indicarle a Chrome que ignore certificados inválidos con --allow-insecure-localhost. Firefox y Safari proporcionan mecanismos integrados para agregar excepciones para certificados de seguridad.

  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "YOUR_OS_APP_ID",
        allowLocalhostAsSecureOrigin: true,
      });
    });
  </script>

Notificación de bienvenida (opcional)

El código personalizado configura la notificación de bienvenida en OneSignal.init() con los parámetros de welcomeNotification. Las integraciones de sitio típico y WordPress la configuran en el panel. Consulta Configuración del Web SDK.

Subir el archivo service worker

El Web SDK busca OneSignalSDKWorker.js en la raíz de tu sitio (https://yourdomain.com/OneSignalSDKWorker.js) a menos que pases una ruta personalizada en OneSignal.init(). El código personalizado no usa los campos Customize service worker paths and filenames del panel. Le indicas al SDK dónde buscar en el código con serviceWorkerPath y serviceWorkerParam. Descarga el archivo desde el panel de OneSignal, o crea un archivo llamado OneSignalSDKWorker.js con esta única línea:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Raíz (predeterminado): Sube el archivo para que esté disponible en https://yourdomain.com/OneSignalSDKWorker.js. No necesitas configurar serviceWorkerPath. El SDK solicita esta URL automáticamente. Subdirectorio: Si tu sitio ya tiene un service worker (por ejemplo, una PWA), coloca el archivo de OneSignal en un subdirectorio como /push/onesignal/ para que no entre en conflicto con el worker que controla /. En ese caso, debes pasar serviceWorkerPath y serviceWorkerParam en OneSignal.init(). Consulta Agregar código al sitio. El archivo debe ser accesible públicamente en https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js.

Si el archivo no está en la raíz del sitio y omites serviceWorkerPath y serviceWorkerParam, el SDK seguirá solicitando https://yourdomain.com/OneSignalSDKWorker.js y el registro del service worker fallará.

Service worker de OneSignal

Combinación de workers, nombres de archivo personalizados y migración desde otros proveedores.

Agregar código al sitio

Agrega este código a la sección <head> de tu sitio web. Reemplaza YOUR_ONESIGNAL_APP_ID con tu App ID del panel de OneSignal. Si OneSignalSDKWorker.js está en la raíz de tu sitio, usa este fragmento:

HTML

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

Si el archivo está en un subdirectorio, agrega serviceWorkerPath y serviceWorkerParam. Estas opciones son la única forma en que el código personalizado le indica al SDK una ubicación fuera de la raíz.

HTML

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

Parámetro	Descripción	Ejemplo
`serviceWorkerPath`	Ruta relativa desde la raíz del sitio al archivo `.js`. No incluyas una barra inicial.	`"push/onesignal/OneSignalSDKWorker.js"`
`serviceWorkerParam.scope`	Ruta de URL que controla el service worker. Usa el mismo directorio que el archivo.	`"/push/onesignal/"`

La persistencia se configura en el código con persistNotification. El interruptor de persistencia del panel no aplica al código personalizado. Si omites la opción, el SDK actualmente trata la persistencia como activada. Configura persistNotification: false para desactivarla. Solo funciona en Chrome y Edge en escritorio. Consulta Persistencia.

Soporte de push web para iOS

Apple comenzó a soportar notificaciones push web en iPhones y iPads con iOS 16.4+. A diferencia de los dispositivos Android donde el push web simplemente “funciona” si se visita en un navegador compatible, Apple agregó algunos requisitos adicionales como un archivo manifest.json y una acción del usuario para agregar tu sitio a su pantalla de inicio.

Configuración push web para iOS

Agrega el archivo manifest.json requerido y guía a los usuarios para agregar tu sitio a su pantalla de inicio.

Certificado Safari Web Push .p12 (opcional, legado)

Deja esto desactivado a menos que ya tengas tu propio certificado .p12 de Safari Web Push y quieras dar soporte a usuarios de Safari legado. Safari moderno (macOS 13+ y iOS 16.4+) usa Web Push basado en estándares con VAPID (Voluntary Application Server Identification). OneSignal gestiona VAPID automáticamente. No necesitas subir un certificado para navegadores Safari modernos. Si ya tienes tu propio .p12 (Apple no admite .p8 para Safari Web Push), súbelo en el panel. Consulta Certificado Safari Web Push .p12.

Probar la integración del SDK de OneSignal

Esta guía le ayuda a verificar que su integración del SDK de OneSignal funciona correctamente mediante la prueba de notificaciones push y el registro de suscripciones.

Verificar suscripciones de web push

Inicie su sitio en un dispositivo de prueba.

Use Chrome, Firefox, Edge o Safari durante las pruebas.
No use el modo incógnito o navegación privada. Los usuarios no pueden suscribirse a notificaciones push en estos modos.
Los avisos deben aparecer según la configuración de sus solicitudes de permiso.
Haga clic en Permitir en el aviso nativo para suscribirse a notificaciones push.

Aviso de permiso nativo del navegador preguntando al usuario si permite o bloquea las notificaciones — Aviso de permiso nativo de web push

Revise su panel de OneSignal

Vaya a Audiencia > Suscripciones.
Debería ver una nueva entrada con el estado Suscrito.

Ha creado exitosamente una suscripción de web push. Las suscripciones de web push se crean cuando los usuarios se suscriben por primera vez a notificaciones push en su sitio.

Configurar suscripciones de prueba

Las suscripciones de prueba son útiles para probar una notificación push antes de enviar un mensaje.

Agregar a Suscripciones de prueba.

En el panel, junto a la suscripción, haga clic en el botón Opciones (tres puntos) y seleccione Agregar a suscripciones de prueba.

Nombre su suscripción.

Nombre la suscripción para que pueda identificar fácilmente su dispositivo más tarde en la pestaña Suscripciones de prueba.

Cree un segmento de usuarios de prueba.

Vaya a Audiencia > Segmentos > Nuevo segmento.

Nombre el segmento.

Nombre el segmento Test Users (el nombre es importante porque se usará más adelante).

Agregue el filtro Test Users y haga clic en Crear segmento.

Editor de segmentos con el filtro Test Users seleccionado y el segmento nombrado Test Users — Crear un segmento 'Test Users' con el filtro Test Users

Ha creado exitosamente un segmento de usuarios de prueba. Ahora podemos probar el envío de mensajes a este dispositivo individual y grupos de usuarios de prueba.

Enviar push de prueba mediante API

Obtenga su clave API de aplicación y ID de aplicación.

En su panel de OneSignal, vaya a Configuración > Claves e IDs.

Actualice el código proporcionado.

Reemplace YOUR_APP_API_KEY y YOUR_APP_ID en el código a continuación con sus claves reales. Este código usa el segmento Test Users que creamos anteriormente.

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

Ejecute el código.

Ejecute el código en su terminal.

Verifique imágenes y entrega confirmada.

Si todos los pasos de configuración se completaron exitosamente, las suscripciones de prueba deberían recibir una notificación.

Solo Chrome admite imágenes. Las imágenes aparecerán pequeñas en la vista de notificación contraída. Expanda la notificación para ver la imagen completa.

Notificación push expandida en Chrome macOS mostrando una imagen personalizada — Notificación push expandida con imagen en Chrome macOS

Verifique la entrega confirmada.

En su panel, vaya a Entrega > Mensajes enviados, luego haga clic en el mensaje para ver las estadísticas. Debería ver la estadística confirmado, lo que significa que el dispositivo recibió el push.

Safari no admite Entrega confirmada.

Informes de mensajes de notificaciones push

Vea estadísticas de entrega, clics y conversiones para sus notificaciones push.

Ha enviado exitosamente una notificación mediante la API a un segmento.

Si las notificaciones no llegan, contacte a support@onesignal.com con lo siguiente:

La solicitud y respuesta de la API (copie y pegue en un archivo .txt)
Su ID de suscripción
La URL de su sitio web con el código de OneSignal

Identificación de usuarios

La sección anterior cubrió la creación de suscripciones de web push. Esta sección expande la identificación de usuarios en todas sus suscripciones (incluyendo push, email y SMS) usando el SDK de OneSignal. Cubre IDs externos, etiquetas, suscripciones multicanal, privacidad y seguimiento de eventos para ayudarle a unificar e involucrar usuarios en todas las plataformas.

Asignar ID externo

Use un ID externo para identificar usuarios de manera consistente en dispositivos, direcciones de correo electrónico y números de teléfono usando el identificador de usuario de su backend. Esto asegura que sus mensajes permanezcan unificados en todos los canales y sistemas de terceros (especialmente importante para integraciones). Establezca el ID externo con el método login del SDK cada vez que un usuario sea identificado por su aplicación.

OneSignal genera IDs únicos de solo lectura para suscripciones (ID de suscripción) y usuarios (ID de OneSignal).A medida que los usuarios descargan su aplicación en diferentes dispositivos, se suscriben a su sitio web y/o le proporcionan direcciones de correo electrónico y números de teléfono fuera de su aplicación, se crearán nuevas suscripciones.Se recomienda encarecidamente establecer el ID externo a través del SDK para identificar usuarios en todas sus suscripciones, independientemente de cómo se creen.

Agregar etiquetas de datos

Las etiquetas son pares clave-valor de datos de cadena que puede usar para almacenar propiedades de usuario (como username, role o preferencias) y eventos (como purchase_date, game_level o interacciones de usuario). Las etiquetas alimentan la personalización de mensajes y segmentación avanzadas, permitiendo casos de uso más avanzados. Establezca etiquetas con los métodos addTag y addTags del SDK a medida que ocurren eventos en su aplicación. En este ejemplo, el usuario alcanzó el nivel 6 identificable por la etiqueta llamada current_level establecida en un valor de 6.

Un perfil de usuario en OneSignal con una etiqueta llamada "current_level" establecida en "6"

Podemos crear un segmento de usuarios que tengan un nivel entre 5 y 10, y usar eso para enviar mensajes dirigidos y personalizados:

Editor de segmentos mostrando un segmento dirigido a usuarios con un valor de current_level mayor que 4 y menor que 10

Captura de pantalla mostrando una notificación push dirigida al segmento Nivel 5-10 con un mensaje personalizado

Agregar suscripciones de email y/o SMS

El SDK de OneSignal crea suscripciones de web push automáticamente cuando los usuarios aceptan. También puede llegar a los usuarios a través de canales de email y SMS creando las suscripciones correspondientes.

Use el método addEmail para crear suscripciones de email.
Use el método addSms para crear suscripciones de SMS.

Si la dirección de correo electrónico y/o número de teléfono ya existen en la aplicación de OneSignal, el SDK lo agregará al usuario existente, no creará duplicados. Puede ver usuarios unificados a través de Audiencia > Usuarios en el panel o con la API de ver usuario.

Un perfil de usuario con suscripciones de push, email y SMS unificadas por ID externo

Mejores prácticas para comunicación multicanal

Obtenga consentimiento explícito antes de agregar suscripciones de email o SMS.
Explique los beneficios de cada canal de comunicación a los usuarios.
Proporcione preferencias de canal para que los usuarios puedan seleccionar qué canales prefieren.

Privacidad y consentimiento del usuario

Para controlar cuándo OneSignal recopila datos del usuario, use los métodos de control de consentimiento del SDK:

setConsentRequired(true): Previene la recopilación de datos hasta que se otorgue el consentimiento.
setConsentGiven(true): Habilita la recopilación de datos una vez que se otorgue el consentimiento.

Para más información sobre privacidad y seguridad:

Datos recopilados por el SDK

Revise qué datos recopila el SDK de OneSignal de los usuarios.

Manejo de datos personales

Gestione y proteja los datos de usuarios en cumplimiento con las normativas de privacidad.

Escuchar eventos de push, usuario e in-app

Use los listeners del SDK para reaccionar a acciones de usuario y cambios de estado. El SDK proporciona varios listeners de eventos a los que puede conectarse. Consulte nuestra guía de referencia del SDK para más detalles.

Eventos de notificación push

Listener de evento de clic: Detecte cuándo se toca una notificación.
Listener de ciclo de vida en primer plano: Controle cómo se comportan las notificaciones en primer plano.

Cambios de estado del usuario

Listener de evento de cambio de estado del usuario: Detecte cuándo se establece el ID externo.
Observador de permisos: Rastree la interacción específica del usuario con el aviso de permiso push nativo.
Observador de cambio de suscripción push: Rastree cuándo cambia el estado de la suscripción push.

Configuración y capacidades avanzadas

Explore más capacidades para mejorar su integración:

Migrar a OneSignal

Migre desde otro proveedor de push a OneSignal.

Integraciones

Conecte OneSignal con herramientas y plataformas de terceros.

Botones de acción

Agregue botones interactivos a las notificaciones push.

Mensajería multiidioma

Envíe mensajes localizados a los usuarios en su idioma preferido.

Verificación de identidad

Proteja su integración del SDK con verificación de identidad en el servidor.

Resultados personalizados

Rastree eventos de conversión personalizados vinculados a sus mensajes.

Configuración y referencia del Web SDK

Configuración de web push

Habilite todas las funciones clave de web push para su integración.

Referencia del Web SDK

Detalles completos sobre métodos disponibles y opciones de configuración.

¡Felicitaciones! Ha completado exitosamente la guía de configuración del Web SDK.

Preguntas frecuentes

¿Dónde busca el Web SDK el service worker?

El Web SDK busca OneSignalSDKWorker.js en la raíz de tu sitio (https://yourdomain.com/OneSignalSDKWorker.js) a menos que pases serviceWorkerPath y serviceWorkerParam en OneSignal.init(). El código personalizado no usa los campos de ruta del panel. Consulta Subir el archivo service worker.

¿Necesito HTTPS para las notificaciones push web?

Sí. Todos los navegadores modernos requieren HTTPS para el soporte de notificaciones push. Si tu sitio usa HTTP, debes migrar a HTTPS antes de configurar el push web.

¿Puedo usar esta configuración con una aplicación de página única (SPA)?

Sí. La configuración de código personalizado es el enfoque recomendado para SPAs construidas con frameworks como React, Angular o Vue. Consulta Configuración Angular, Configuración React JS y Configuración Vue JS.

¿Qué sucede si un usuario borra los datos de su navegador?

La suscripción push del usuario se elimina. Si Auto Resubscribe está habilitado, se resuscribe automáticamente la próxima vez que visite tu sitio.

​Requisitos

​Configurar tu aplicación y plataforma OneSignal

​Configuración del sitio

​Pruebas locales

​Notificación de bienvenida (opcional)

​Subir el archivo service worker

Service worker de OneSignal

​Agregar código al sitio

​Soporte de push web para iOS

Configuración push web para iOS

​Certificado Safari Web Push .p12 (opcional, legado)

​Probar la integración del SDK de OneSignal

​Verificar suscripciones de web push

​Configurar suscripciones de prueba

​Enviar push de prueba mediante API

Informes de mensajes de notificaciones push

​Identificación de usuarios

​Asignar ID externo

​Agregar etiquetas de datos

​Agregar suscripciones de email y/o SMS

​Privacidad y consentimiento del usuario

Datos recopilados por el SDK

Manejo de datos personales

​Escuchar eventos de push, usuario e in-app

​Eventos de notificación push

​Cambios de estado del usuario

​Configuración y capacidades avanzadas

Migrar a OneSignal

Integraciones

Botones de acción

Mensajería multiidioma

Verificación de identidad

Resultados personalizados

​Configuración y referencia del Web SDK

Configuración de web push

Referencia del Web SDK

​Preguntas frecuentes

​¿Dónde busca el Web SDK el service worker?

​¿Necesito HTTPS para las notificaciones push web?

​¿Puedo usar esta configuración con una aplicación de página única (SPA)?

​¿Qué sucede si un usuario borra los datos de su navegador?

​Páginas relacionadas

Solicitudes de permiso

Referencia del Web SDK

Requisitos

Configurar tu aplicación y plataforma OneSignal

Configuración del sitio

Pruebas locales

Notificación de bienvenida (opcional)

Subir el archivo service worker

Agregar código al sitio

Soporte de push web para iOS

Certificado Safari Web Push .p12 (opcional, legado)

Probar la integración del SDK de OneSignal

Verificar suscripciones de web push

Configurar suscripciones de prueba

Enviar push de prueba mediante API

Identificación de usuarios

Asignar ID externo

Agregar etiquetas de datos

Agregar suscripciones de email y/o SMS

Privacidad y consentimiento del usuario

Escuchar eventos de push, usuario e in-app

Eventos de notificación push

Cambios de estado del usuario

Configuración y capacidades avanzadas

Configuración y referencia del Web SDK

Preguntas frecuentes

¿Dónde busca el Web SDK el service worker?

¿Necesito HTTPS para las notificaciones push web?

¿Puedo usar esta configuración con una aplicación de página única (SPA)?

¿Qué sucede si un usuario borra los datos de su navegador?

Páginas relacionadas