# Widget de suscripción El **widget de suscripción** es un lanzador en forma de campana más un aviso que invita a los visitantes del sitio a suscribirse a las notificaciones push. Sustituye al [botón de suscripción a notificaciones push](/es/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/), al [Popup de suscripción personalizado](/es/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) y a los widgets de [solicitud de suscripción](/es/developer/guides/messaging-channels/subscription-prompt/) en un solo componente. Mientras está habilitado, ninguno de esos tres se carga en la página, por lo que los visitantes nunca ven dos solicitudes compitiendo entre sí. Un visitante que aún no ha decidido ve la solicitud. 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](/es/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration). ## 1. Habilitar el widget Añade el parámetro `subscriptionWidget` a la inicialización del WebSDK y establece `enable` en `true`: ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, } }]); ``` Todos los campos siguientes son opcionales. Un campo 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. El formulario del Panel de Control descrito más adelante rechaza directamente un valor no válido y se niega a guardarlo. ## 2. Configurar el aviso ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, prompt: { 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 size: 48, // 32–80 }, 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 mostrarlo `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`** — se abre solo cuando el visitante hace clic en la campana. - **`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 mientras el visitante no está suscrito, independientemente de `display.trigger` — incluso con `trigger: 'auto'`, la campana permanece visible para que el visitante pueda volver a abrir el aviso después de cerrarlo. `launcher.position` la coloca en una de las cuatro esquinas. `launcher.offset` (píxeles desde los bordes) y `launcher.size` (el diámetro de la campana en píxeles) ajustan su posición. ### 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. El formulario del Panel de Control valida cada campo de esta manera, hasta 64 caracteres. El fragmento de inicialización acepta cualquier cadena no vacía para estos campos sin comprobar su formato o longitud. ## Gestionarlo en el Panel de Control En una aplicación gestionada desde el panel, ve a **Settings → Configure platforms → Web** y abre la tarjeta **Subscription widget**. Una insignia en la tarjeta muestra si el widget está **On** u **Off**. Haz clic en **Configure** para editar los mismos campos descritos anteriormente, agrupados como **Prompt**, **When to show**, **Bell**, **Texts** y **Colors**, junto a una vista previa en vivo que muestra tanto el estado de visitante indeciso como el de visitante bloqueado. Guardar reemplaza la copia de la configuración del widget en el panel. No modifica el fragmento de inicialización del WebSDK en tu sitio. Mientras una aplicación esté gestionada desde el panel, los valores guardados en esta tarjeta anulan las mismas claves en el fragmento de inicialización del sitio. Cambiar un sitio a la configuración del panel es un interruptor en el panel, sin cambios de código en el sitio. ## 3. Controlar el widget desde tu código Una vez que se ha cargado el paquete del widget, publica una API en `Pushwoosh.moduleRegistry.subscriptionWidget`: ```javascript 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()` no tiene efecto para un visitante que ya se suscribió. Abrir el aviso despacha un evento `show-subscription-widget`. Cerrarlo despacha `hide-subscription-widget`: ```javascript 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.enable` permanezca sin definir o en `false`. Establecerlo en `true` detiene la carga de los tres, tanto en una aplicación configurada mediante fragmento como en una gestionada desde el panel.