Widget de suscripción

El widget de suscripción es un aviso y una campana lanzadora que invitan a los visitantes del sitio a suscribirse a las notificaciones push, configurados juntos como subscriptionWidget pero activados de forma independiente: solo el aviso, solo la campana, o ambos a la vez. Activar cualquiera de los dos sustituye al botón de suscripción a notificaciones push, al Popup de suscripción personalizado y a la solicitud de suscripción — mientras al menos una de las dos partes esté activada, ninguno de esos tres widgets anteriores se carga en la página.

Un visitante que aún no ha decidido ve la solicitud del aviso. Un visitante que ya bloqueó las notificaciones ve en su lugar una explicación de cómo desbloquearlas.

Requisitos previos

Asegúrate de haber implementado Pushwoosh Web SDK 3.0 en tu sitio web. Para ello, sigue nuestra guía de integración.

1. Activar el aviso y la campana

Añade el parámetro subscriptionWidget a la inicialización del WebSDK y establece prompt.enabled y/o launcher.enabled en true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

Sin interruptor único de nivel superior

El campo subscriptionWidget.enable de nivel superior no se lee. Establecer solo ese campo no activa nada. Consulta Migración desde los widgets anteriores más abajo.

Todos los campos siguientes son opcionales. Uno omitido recurre a su valor predeterminado. En el fragmento de inicialización, un número fuera de su rango se ajusta silenciosamente al límite más cercano y un valor de enumeración no válido recurre silenciosamente a su valor predeterminado, sin advertencia en la consola. Los formularios del Panel de Control descritos más adelante validan cada campo y se niegan a guardar uno no válido.

2. Configurar el aviso y la campana

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

Diseño y posición

prompt.layout establece la forma del aviso:

• card — una tarjeta compacta anclada a un borde o una esquina. prompt.position acepta top, bottom, top-left, top-right, bottom-left o bottom-right.
• bar — una barra que ocupa todo el ancho de la página. prompt.position solo acepta top o bottom.
• modal — una ventana centrada en la página. prompt.position es siempre center.

Consulta la lista anterior para conocer el diseño configurado antes de elegir una posición. En el fragmento de inicialización, una posición que el diseño actual no admite se sustituye silenciosamente por el valor predeterminado del diseño. El formulario del Panel de Control rechaza esa combinación en su lugar.

Cuándo mostrar el aviso

display.trigger controla qué abre el aviso:

• auto — se abre automáticamente display.delay segundos después de que carga la página, y luego de nuevo cada display.cappingInterval horas si el visitante no ha decidido, hasta display.cappingCount veces en total (0 significa sin límite).
• launcher — nunca se abre por temporizador. Establécelo junto con launcher.enabled: true para que un clic en la campana pueda abrirlo. La API manual lo abre igualmente, sin importar este ajuste ni si la campana está activada.
• manual — se abre solo mediante Pushwoosh.moduleRegistry.subscriptionWidget, descrito más abajo.

display.delay, display.cappingCount y display.cappingInterval solo se aplican al disparador auto.

La campana lanzadora

launcher.enabled muestra una campana flotante a un visitante que todavía puede actuar ante la solicitud (aún no suscrito, o bloqueado), independientemente del aviso y de display.trigger. La campana permanece en pantalla mientras el aviso está abierto. launcher.position la coloca en una de las cuatro esquinas. launcher.offset establece su distancia a los bordes, en píxeles.

El efecto de un clic en la campana depende del aviso. Si prompt.enabled es true, el clic lo alterna: lo abre, o lo cierra si ya está abierto. Si el aviso está desactivado, el clic solicita el permiso al navegador directamente, igual que Pushwoosh.subscribe() — salvo que el visitante ya haya bloqueado las notificaciones, en cuyo caso el clic no hace nada.

launcher.width y launcher.height establecen el tamaño de la campana en píxeles (16–200, 48 por defecto para cada uno). launcher.imageUrl dibuja una imagen en lugar del botón redondo con forma de campana. launcher.background y launcher.iconColor establecen el relleno y el color del glifo del botón redondo. Si no se definen, launcher.background toma por defecto el color de acento de la paleta y launcher.iconColor un color de glifo calculado para contrastar con él.

Textos y colores

texts.blockedTitle, texts.blockedMessage y texts.closeText se muestran en lugar de la solicitud una vez que el navegador informa que el visitante bloqueó las notificaciones — texts.acceptText y texts.declineText nunca aparecen en ese estado. texts.launcherLabel y texts.launcherBlockedLabel son el texto emergente de la campana en cada estado. Cada campo de texto acepta hasta 300 caracteres.

colors.accent, colors.background, colors.text y colors.textSecondary aceptan un valor hexadecimal o un nombre de color CSS. Los formularios del Panel de Control validan cada uno de ellos, y también launcher.background/launcher.iconColor, de esta manera, hasta 64 caracteres. El fragmento de inicialización acepta cualquier cadena no vacía para colors.* sin comprobar formato ni longitud. Para launcher.background/launcher.iconColor no comprueba el formato, pero recorta silenciosamente el valor a 64 caracteres.

Nota

Una paleta de modo oscuro, launcher.zIndex y una fontFamily personalizada están disponibles como campos adicionales solo del fragmento de inicialización. No están expuestos en los formularios del Panel de Control descritos a continuación.

Gestionarlo en el Panel de Control

Solo para aplicaciones gestionadas desde el panel

Las tarjetas del Panel de Control solo están disponibles para aplicaciones con la plataforma Web en modo gestionado desde el panel (consulta Web Push SDK 3.0). Para una aplicación configurada mediante fragmento, establece subscriptionWidget en el fragmento de inicialización como se mostró antes.

En una aplicación gestionada desde el panel, ve a Settings → Configure platforms → Web. El aviso y la campana son dos tarjetas distintas allí, cada una con su propia insignia On/Off y su botón Configure:

• Subscription invitation edita el aviso: Invitation (diseño, posición, icono), When to show (disparador, retraso, límite de frecuencia), Texts y Colors.
• Subscription bell edita el lanzador: posición, URL de la imagen, ancho/alto, color de fondo y del icono, y sus propios textos emergentes.

El botón Configure de cada tarjeta abre una vista previa en vivo junto al formulario. La vista previa no dibuja nada mientras el interruptor de esa tarjeta está desactivado. Una vez activado, un menú desplegable sobre la vista previa alterna entre la solicitud al visitante indeciso y la explicación para el visitante bloqueado. Guardar una tarjeta reemplaza solo su mitad de la copia de la configuración del widget en el panel — los ajustes de la otra tarjeta y el fragmento de inicialización del WebSDK en tu sitio no se modifican.

Mientras una aplicación esté gestionada desde el panel, los valores guardados en cualquiera de las dos tarjetas anulan las mismas claves en el fragmento de inicialización del sitio.

3. Controlar el aviso desde tu código

Una vez que se ha cargado el paquete del widget, publica una API en Pushwoosh.moduleRegistry.subscriptionWidget:

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

show() y toggle() no tienen efecto mientras prompt.enabled sea false, ni para un visitante que ya se suscribió. Abrir el aviso despacha un evento show-subscription-widget. Cerrarlo despacha hide-subscription-widget:

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

Migración desde los widgets anteriores

El botón de suscripción a notificaciones push, el Popup de suscripción personalizado y la solicitud de suscripción siguen funcionando tal como se documenta en sus propias páginas mientras subscriptionWidget.prompt.enabled y subscriptionWidget.launcher.enabled del sitio permanezcan ambos sin definir o en false. Activar cualquiera de los dos detiene la carga de los tres, tanto en una aplicación configurada mediante fragmento como en una gestionada desde el panel.

Precaución

Una versión anterior del widget usaba un único interruptor de nivel superior subscriptionWidget.enable en lugar de prompt.enabled/launcher.enabled por separado. Esa forma ya no se lee. Un fragmento que aún establezca solo enable: true ahora desactiva el widget por completo: ni el aviso ni la campana dibujan nada, el WebSDK registra en la consola una pista que nombra los dos campos que deben establecerse, y los tres widgets anteriores se cargan como si subscriptionWidget nunca se hubiera definido. Cambiar una aplicación gestionada desde el panel al nuevo widget tampoco traslada la configuración de cualquiera que sea el widget antiguo que sustituye — cada tarjeta parte de sus propios valores predeterminados.