SDK de Web Push 3.0
Integración
Anchor link toEjemplo de integración en GitHub
Obtenga el SDK de Web Push de Pushwoosh y descomprímalo. Debería tener los siguientes archivos:
Anchor link to- pushwoosh-service-worker.js
Coloque todos estos archivos en el directorio raíz de nivel superior de su sitio web.
Anchor link toInicialice el SDK:
Anchor link to- Incluya el SDK desde nuestro CDN de forma asíncrona.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>- Inicialice el SDK de Web Push y asegúrese de poner en cola la inicialización hasta el momento en que el SDK esté completamente cargado.
<script type="text/javascript">var Pushwoosh = Pushwoosh || [];Pushwoosh.push(['init', { logLevel: 'info', // valores posibles: error, info, debug applicationCode: 'XXXXX-XXXXX', // el código de su aplicación desde el Panel de Control de Pushwoosh apiToken: 'XXXXXXX', // Token de API de dispositivo safariWebsitePushID: 'web.com.example.domain', // cadena de dominio inverso única, obtenida en su Portal de Desarrolladores de Apple. Solo es necesario si envía notificaciones push al navegador Safari defaultNotificationTitle: 'Pushwoosh', // establece un título predeterminado para las notificaciones push defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL a la imagen de notificación personalizada autoSubscribe: false, // o true. Si es true, solicita al usuario que se suscriba a las notificaciones push al inicializar el SDK subscribeWidget: { enable: true }, userId: 'user_id', // opcional, establezca un ID de usuario personalizado tags: { 'Name': 'John Smith' // opcional, establezca Tags personalizados }}]);</script>Popups web
Anchor link toAñada webPopups a su objeto init para habilitar las campañas de popups web en su sitio.
webPopups: { enable: true, autoShow: true, // opcional, establezca en false para cargar los popups sin mostrarlos automáticamente — consulte los métodos de WebPopups a continuación colorScheme: 'auto', // opcional, 'auto' (predeterminado) | 'light' | 'dark'},Las campañas de popups web muestran superposiciones que usted configura en el Panel de Control, como promociones, anuncios o formularios de captación de clientes potenciales. A diferencia del popup de suscripción personalizado (subscribePopup), que solo gestiona la suscripción a notificaciones push web, las campañas de popups web pueden mostrar cualquier contenido que configure.
Para la configuración en el Panel de Control, consulte Entender los popups web.
colorScheme elige con qué paleta se renderiza un popup configurado con modo oscuro:
'auto'(predeterminado): sigue el esquema de color del sistema operativo del visitante (prefers-color-scheme).'light'o'dark': siempre renderiza esa paleta, independientemente de la configuración del sistema operativo del visitante.
Un popup sin modo oscuro configurado en el editor siempre se renderiza en modo claro — colorScheme no tiene efecto sobre él.
Para el control programático, consulte los métodos de WebPopups y los eventos de popups web.
Botón de suscripción a notificaciones push
Anchor link toPara solicitar a sus usuarios que se suscriban a las notificaciones push, recomendamos implementar un botón de suscripción a notificaciones push en su sitio web. ¡Mejore la experiencia del usuario y consiga más suscriptores!
Configuración
Anchor link toPara terminar de implementar las notificaciones push en su sitio web, necesita configurar las plataformas web en su Panel de Control de Pushwoosh siguiendo nuestras guías paso a paso:
Registro del service worker en un ámbito diferente
Anchor link toA veces no se puede colocar el archivo del service worker en un directorio raíz de un sitio web, sino en un subdirectorio.
En este caso, modifique la configuración (paso 4.3) añadiendo un parámetro
serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”
donde /push-notifications/pushwoosh-service-worker.js es la ruta al archivo pushwoosh-service-worker.js.
Manejadores de eventos
Anchor link toEn el SDK de Web de Pushwoosh 3.0 puede suscribirse a ciertos eventos para rastrearlos**,** o darse de baja de los eventos si ya no necesita rastrearlos.
Para rastrear la carga del SDK de Web 3.0, dispare el evento onLoad de la siguiente manera:
// Evento de cargaPushwoosh.push(['onLoad', (api) => { console.log('¡Pushwoosh cargado!');}]);Para rastrear la inicialización correcta del SDK de Web, dispare el evento onReady:
// Evento de listoPushwoosh.push((api) => { console.log('¡Pushwoosh listo!');});Para suscribirse o darse de baja de cualquiera de los eventos del SDK, use los manejadores después de la carga del SDK:
Pushwoosh.push(['onLoad', (api) => { function onEventNameHandler() { console.log('Evento disparado: event-name!'); }
// Para suscribirse a un evento: Pushwoosh.addEventHandler('event-name', onEventNameHandler)
// Para darse de baja de un evento: Pushwoosh.removeEventHandler('event-name', onEventNameHandler)}]);Eventos del SDK
Anchor link toEvento de suscripción
Anchor link toSe ejecuta después de que un usuario acepta recibir notificaciones push.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('subscribe', (payload) => { console.log('Evento disparado: subscribe'); });}]);Evento de cancelación de suscripción
Anchor link toSe ejecuta después de que un dispositivo se da de baja de las notificaciones.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('unsubscribe', (payload) => { console.log('Evento disparado: unsubscribe'); });}]);Eventos del widget de suscripción
Anchor link toRastrea la visualización de un widget de Solicitud de Suscripción.
Pushwoosh.push(['onLoad', (api) => { // Se ejecuta al mostrar el widget de Solicitud de Suscripción Pushwoosh.addEventHandler('show-subscription-widget', (payload) => { console.log('Evento disparado: show-subscription-widget'); });
// Se ejecuta al ocultar el widget de Solicitud de Suscripción Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => { console.log('Evento disparado: hide-subscription-widget'); });}]);Eventos del diálogo de permiso de notificación
Anchor link toRastrea la visualización del diálogo de suscripción nativo.
Pushwoosh.push(['onLoad', function (api) { // Se ejecuta al mostrar el diálogo de permiso Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => { console.log('Evento disparado: show-notification-permission-dialog'); });
// Se ejecuta al ocultar el diálogo de permiso con uno de los tres estados posibles: // 1. default - el diálogo se cierra // 2. granted - se concede el permiso // 3. denied - se deniega el permiso Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => { console.log('Evento disparado: hide-notification-permission-dialog', payload.permission); });}]);Eventos de permiso
Anchor link toComprueba el estado del permiso de notificaciones push en la inicialización del SDK; rastrea la actualización de este estado cada vez que tiene lugar.
Pushwoosh.push(['onLoad', (api) => { // Se ejecuta durante la inicialización del SDK si 'autoSubscribe: false' y/o si un usuario ignora una solicitud de notificación push. Pushwoosh.addEventHandler('permission-default', (payload) => { console.log('Evento disparado: permission-default'); });
// Se ejecuta durante la inicialización del SDK si las notificaciones están bloqueadas o una vez que un usuario bloquea las notificaciones push. Pushwoosh.addEventHandler('permission-denied', (payload) => { console.log('Evento disparado: permission-denied'); });
// Se ejecuta durante la inicialización del SDK si las notificaciones están permitidas o una vez que un usuario permite las notificaciones push. Pushwoosh.addEventHandler('permission-granted', (payload) => { console.log('Evento disparado: permission-granted'); });}]);Evento de recepción de push
Anchor link toRastrea la entrega de notificaciones push a un dispositivo.
Pushwoosh.push(['onLoad', (api) => { // Se ejecuta cuando se muestra una notificación push. Pushwoosh.addEventHandler('receive-push', (payload) => { console.log('Evento disparado: receive-push', payload.notification); });}]);Eventos de notificación
Anchor link toRastrea si un usuario abre o cierra una notificación push.
Pushwoosh.push(['onLoad', (api) => { // Se ejecuta cuando un usuario hace clic en la notificación. Pushwoosh.addEventHandler('open-notification', (payload) => { console.log('Evento disparado: open-notification', payload.notification); });
// Se ejecuta cuando un usuario cierra una notificación push. Pushwoosh.addEventHandler('hide-notification', (payload) => { console.log('Evento disparado: hide-notification', payload.notification); });}]);Eventos de la bandeja de entrada
Anchor link toRastrea las notificaciones enviadas a la Bandeja de entrada.
Pushwoosh.push(['onLoad', (api) => { // Ejecutado por el ServiceWorker después de que el Mensaje de la Bandeja de entrada se recibe y se guarda en indexedDB. Pushwoosh.addEventHandler('receive-inbox-message', (payload) => { console.log('Evento disparado: receive-inbox-message', payload.message); });
// Se ejecuta después de que la Bandeja de entrada se actualiza automáticamente mientras se carga la página. Pushwoosh.addEventHandler('update-inbox-messages', (payload) => { console.log('Evento disparado: receive-inbox-message', payload.messages); });}]);Eventos del popup de suscripción personalizado
Anchor link toPara obtener detalles sobre el manejo de los eventos del popup de suscripción personalizado, consulte la Guía de Eventos del Popup de Suscripción Personalizado.
Eventos de popups web
Anchor link toPushwoosh.push(['onLoad', (api) => { // Se ejecuta una vez que los popups web se han cargado y la tubería de visualización automática se ha ejecutado para la página actual Pushwoosh.addEventHandler('web-popups-ready', () => { console.log('Evento disparado: web-popups-ready'); });
// Se ejecuta cuando se muestra un popup web, automáticamente o a través de webPopups.show() Pushwoosh.addEventHandler('show-web-popup', (payload) => { console.log('Evento disparado: show-web-popup', payload.code, payload.trigger); // disparador: 'auto' | 'api' });
// Se ejecuta cuando se oculta un popup web Pushwoosh.addEventHandler('hide-web-popup', (payload) => { console.log('Evento disparado: hide-web-popup', payload.code, payload.reason); // razón: 'user' | 'api' | 'preempted' });}]);Después de inicializar el SDK de Web Push, puede realizar las siguientes llamadas a la API de Pushwoosh. Todos los métodos devuelven objetos Promise.
Pushwoosh.push((api) => { // Establecer tags para un usuario api.setTags({ 'Tag Name 1': 'value1', 'Tag Name 2': 'value2' });
// Obtener tags para un usuario desde el servidor api.getTags();
// Registrar ID de usuario api.registerUser('user123');
// Registrar correo electrónico de usuario api.registerEmail('user@example.com');
// Registrar número de SMS api.registerSmsNumber('+15551234567');
// Registrar número de WhatsApp api.registerWhatsappNumber('+1234567890');
// Publicar un Evento api.postEvent('myEventName', {attributeName: 'attributeValue'});
//Darse de baja de las notificaciones api.unregisterDevice();
// Establecer el idioma del dispositivo (sobrescribe el valor en el Tag "Language") api.setLanguage('es');
// Alternativamente, multiregistro de usuario con dispositivos y canales api.multiRegisterDevice({ user_id: 'user123', email: 'user@example.com', sms_phone_number: '+1234567890', tags: { 'UserType': { operation: TTagOperationSet, value: 'Premium' }, 'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] } } });});multiRegisterDevice
Anchor link toMétodo de registro mejorado que permite registrar un perfil de usuario con múltiples dispositivos y canales de mensajería en una sola llamada a la API. Este método es particularmente útil para aplicaciones multiplataforma o al implementar estrategias de mensajería omnicanal.
Pushwoosh.push((api) => { api.multiRegisterDevice({ user_id: 'user123', // Opcional: Identificador de usuario email: 'user@example.com', // Opcional: Correo electrónico para mensajería por correo electrónico sms_phone_number: '+1234567890', // Opcional: Número de teléfono SMS (formato E.164) whatsapp_phone_number: '+1234567890', // Opcional: Número de WhatsApp (formato E.164) kakao_phone_number: '+1234567890', // Opcional: Número de KakaoTalk (formato E.164) language: 'en', // Opcional: Código de idioma (ISO 639-1) timezone: 'America/New_York', // Opcional: Identificador de zona horaria city: 'New York', // Opcional: Ciudad para segmentación country: 'US', // Opcional: País para segmentación state: 'NY', // Opcional: Estado para segmentación tags: { // Opcional: Valores de tag con operaciones 'UserType': { operation: TTagOperationSet, // Establecer valor de tag (0) value: 'Premium' }, 'Interests': { operation: TTagOperationAppend, // Añadir al valor de tag (1) values: ['sports', 'technology'] }, 'LoginCount': { operation: TTagOperationIncrement, // Incrementar valor de tag (3) value: '1' } }, push_devices: [ // Opcional: Array de dispositivos push { hwid: 'web-device-456', platform: TPlatformChrome, // Plataforma Chrome (11) push_token: 'fcm-token-here', app_version: '2.1.0', platformData: { public_key: 'web-push-public-key', auth_token: 'web-push-auth-token', browser: 'chrome' } } ] }) .then((response) => { console.log('Multiregistro exitoso:', response); }) .catch((error) => { console.error('Multiregistro fallido:', error); });});Tipos de plataforma:
TPlatformSafari(10): Plataforma SafariTPlatformChrome(11): Plataforma ChromeTPlatformFirefox(12): Plataforma Firefox
Tipos de operación de Tag:
TTagOperationSet(0): Establecer valor de tag (reemplaza el valor existente)TTagOperationAppend(1): Añadir al valor de tag (añadir a la lista)TTagOperationRemove(2): Eliminar valor de tag (eliminar de la lista)TTagOperationIncrement(3): Incrementar valor de tag (incremento numérico)
Beneficios:
- Llamada única a la API: Registra múltiples dispositivos y canales a la vez
- Operación atómica: Todos los registros tienen éxito o fallan juntos
- Centrado en el usuario: Asocia todos los dispositivos con un único perfil de usuario
- Etiquetado avanzado: Admite operaciones complejas de tags
- Multiplataforma: Maneja múltiples plataformas simultáneamente
Ejemplo de envío de Tags a Pushwoosh:
Pushwoosh.push((api) => { var myCustomTags = { 'Tag 1': 123, 'Tag 2': 'some string' }; api.setTags(myCustomTags) .then((res) => { var skipped = res && res.skipped || []; if (!skipped.length) { console.log('éxito'); } else { console.warn('tags omitidos:', skipped); } }) .catch((err) => { console.error('error en setTags:', err); });});Incrementar valor de Tag
Anchor link toPara incrementar un valor de un Tag numérico, use el parámetro operation con el valor ‘increment’ de la siguiente manera:
Pushwoosh.push((api) => { api.setTags({ 'Tag 1': { operation: 'increment', value: 1 } })});Añadir valores de Tag
Anchor link toPara añadir nuevos valores al Tag de lista existente, use el parámetro operation con el valor ‘append’ de la siguiente manera:
Pushwoosh.push((api) => { api.setTags({ 'Tag 3': { operation: 'append', value: ['Value3'] } })});Eliminar valor de Tag
Anchor link toPara eliminar un valor de un Tag de lista, use el parámetro operation con el valor ‘remove’ de la siguiente manera:
Pushwoosh.push((api) =>{ api.setTags({ 'Tag 3': { operation: 'remove', value: ['Value2'] } })});Métodos públicos
Anchor link toPushwoosh.subscribe()
Este método se utiliza para solicitar el permiso de un usuario para las notificaciones push. Si un usuario ya está suscrito, el método dejará de ejecutarse.
Si un usuario aún no se ha suscrito a las notificaciones push:
1. Se solicita el permiso para las notificaciones push.

2. Si un usuario permite las notificaciones, se dispara el evento onSubscribe.
Pushwoosh.subscribe() se ejecuta automáticamente si se establece autoSubscribe: true durante la inicialización del SDK.
Llame a este método si ha elegido solicitar manualmente a un usuario que se suscriba a las notificaciones push utilizando el parámetro autoSubscribe: false durante la inicialización:
<button onclick="Pushwoosh.subscribe()">Suscribirse</button><script> Pushwoosh.push(['onSubscribe', (api) => { console.log('Usuario suscrito con éxito'); }]);</script>Pushwoosh.unsubscribe()
- Se ejecuta el método
/unregisterDevice. - Se dispara el evento
onUnsubscribe.
<button onclick="Pushwoosh.unsubscribe()">Darse de baja</button><script type="text/javascript"> Pushwoosh.push(['onUnsubscribe', (api) => { console.log('Usuario dado de baja con éxito'); }]);</script>Pushwoosh.isSubscribed()
Comprueba si un usuario está suscrito y devuelve un indicador verdadero/falso.
Pushwoosh.isSubscribed().then((isSubscribed) => { console.log('isSubscribed', isSubscribed);});Pushwoosh.getHWID()
Devuelve el HWID de Pushwoosh.
Pushwoosh.getHWID().then((hwid) => { console.log('hwid:', hwid);});Pushwoosh.getPushToken()
Devuelve el token de push si está disponible.
Pushwoosh.getPushToken().then((pushToken) => { console.log('pushToken:', pushToken);});Pushwoosh.getUserId()
Devuelve el ID de Usuario si está disponible.
Pushwoosh.getUserId().then((userId) => { console.log('userId:', userId);});Pushwoosh.getParams()
Devuelve una lista de los siguientes parámetros:
Pushwoosh.getParams().then((params) => { params = params || {}; var hwid = params.hwid; var pushToken = params.pushToken; var userId = params.userId;});Pushwoosh.isAvailableNotifications()
Comprueba si un navegador es compatible con el WebSDK 3.0 de Pushwoosh, devuelve ‘true’ o ‘false’.
Pushwoosh.isAvailableNotifications() // true/falseMétodos de InboxMessages
Anchor link tomessagesWithNoActionPerformedCount(): Promise<number>
Devuelve el número de mensajes abiertos.
Pushwoosh.pwinbox.messagesWithNoActionPerformedCount() .then((count) => { console.log(`${count} mensajes abiertos`); });unreadMessagesCount()
Devuelve el número de mensajes no leídos.
Pushwoosh.pwinbox.unreadMessagesCount() .then((count) => { console.log(`${count} mensajes no leídos`); });messagesCount(): Promise<number>
Devuelve el número total de mensajes.
Pushwoosh.pwinbox.messagesCount() .then((count) => { console.log(`${count} mensajes`); });loadMessages(): Promise<Array>
Carga la lista de mensajes no eliminados.
Pushwoosh.pwinbox.loadMessages() .then(() => { console.log('Los mensajes han sido cargados'); });readMessagesWithCodes(codes: Array<string>): Promise<void>
Marca los mensajes como leídos por Inbox_Ids.
Pushwoosh.pwinbox.readMessagesWithCodes(codes) .then(() => { console.log('Los mensajes han sido leídos'); });performActionForMessageWithCode(code: string): Promise<void>
Realiza la acción asignada a un mensaje y lo marca como leído.
Pushwoosh.pwinbox.performActionForMessageWithCode(code) .then(() => { console.log('La acción ha sido realizada'); });deleteMessagesWithCodes(codes: Array<string>): Promise<void>
Marca los mensajes como eliminados.
Pushwoosh.pwinbox.deleteMessagesWithCodes([code]) .then(() => { console.log('Los mensajes han sido eliminados'); });syncMessages(): Promise<void>
Sincroniza los mensajes con el servidor.
Pushwoosh.pwinbox.syncMessages() .then(() => { console.log('Los mensajes han sido sincronizados'); });Métodos de WebPopups
Anchor link toLa API programática de popups web requiere webPopups: {enable: true} en el objeto init; está disponible a través de Pushwoosh.moduleRegistry.webPopups una vez que se ha disparado el evento web-popups-ready.
show(code: string): Promise<boolean>
Muestra un popup inmediatamente, omitiendo todas las condiciones de visualización (retraso, reglas de página, tipo de dispositivo/visitante, limitación de frecuencia, tipo de disparador). Cierra un popup ya visible para hacer espacio. Resuelve a false en lugar de rechazar cuando el popup no se puede mostrar.
Pushwoosh.moduleRegistry.webPopups.show('popup_code') .then((shown) => console.log('Popup mostrado:', shown));hide(code?: string): boolean
Oculta el popup visible. Si se pasa code, solo lo oculta cuando coincide con el popup visible. Devuelve false si no se ocultó nada.
Pushwoosh.moduleRegistry.webPopups.hide();hideAll(): boolean
Oculta el popup visible y descarta todo lo que aún esté pendiente para la carga de la página actual. show() sigue funcionando después.
Pushwoosh.moduleRegistry.webPopups.hideAll();isVisible(code?: string): boolean
Comprueba si un popup está visible actualmente. Sin code, comprueba si hay algún popup visible.
Pushwoosh.moduleRegistry.webPopups.isVisible('popup_code');getVisibleCode(): string | null
Devuelve el código del popup actualmente en pantalla, o null si no hay ninguno visible.
Pushwoosh.moduleRegistry.webPopups.getVisibleCode();getAvailableCodes(): Array<string>
Devuelve los códigos de cada popup que el servidor devolvió para este dispositivo.
Pushwoosh.moduleRegistry.webPopups.getAvailableCodes();getState(): object
Devuelve una instantánea del estado del popup web: visible (código en pantalla, o null), queued (códigos esperando el espacio de visualización), waiting (códigos con un temporizador de retraso activado) y available (todos los códigos que el servidor devolvió).
Pushwoosh.moduleRegistry.webPopups.getState();Soporte para Progressive Web App
Anchor link toPara integrar Pushwoosh en su Progressive Web Application (PWA), siga los pasos que se describen a continuación.
1. Copie la ruta a su archivo de Service Worker:
if ('serviceWorker' in navigator) { window.addEventListener('load', () => { navigator.serviceWorker.register('/service-worker.js') // <- la URL de su service worker });}Luego, use el parámetro serviceWorkerUrl al inicializar el WebSDK de la siguiente manera:
var Pushwoosh = Pushwoosh || [];Pushwoosh.push(['init', { logLevel: 'error', applicationCode: 'XXXXX-XXXXX', safariWebsitePushID: 'web.com.example.domain', defaultNotificationTitle: 'Pushwoosh', defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', serviceWorkerUrl: '/service-worker.js', // <- la URL de su service worker}]);El WebSDK no registra el nuevo Service Worker inmediatamente; un Service Worker se registra cuando es necesario:
- cuando un dispositivo recibe un token de push (en el registro del dispositivo o en la resubscripción),
- cuando se elimina un token de push (al eliminar un dispositivo de la base de usuarios).
Acelera la carga de sus páginas al reducir el número de solicitudes al servidor.
Los navegadores no permiten que se registren dos Service Workers diferentes al mismo timepo (lea más: https://github.com/w3c/ServiceWorker/issues/921), por lo que para que su PWA funcione correctamente, se debe registrar un Service Worker común para su base de código y la base de código de Pushwoosh.
2. Añada la siguiente cadena a su Service Worker (al principio o al final, no importa):
importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);De este modo, habilita la recepción y el procesamiento de las notificaciones push enviadas a través de los servicios de Pushwoosh para su Service Worker.
Instalación desde Google Tag Manager
Anchor link toUse el siguiente código en su Google Tag Manager para inicializar el SDK de Pushwoosh. Cree una etiqueta HTML personalizada y pegue el código a continuación. Asegúrese de cambiar su Código de Aplicación de Pushwoosh, el ID del sitio web de Safari y la URL de la imagen de notificación predeterminada.
También establezca una prioridad alta de Disparo de Etiqueta (ej: 100) y actívela en Todas las Páginas. Vea una captura de pantalla a continuación.Copiar
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script><script type="text/javascript"> var Pushwoosh = Pushwoosh || []; Pushwoosh.push(['init', { logLevel: 'error', applicationCode: 'XXXXX-XXXXX', safariWebsitePushID: 'web.com.example.domain', defaultNotificationTitle: 'Pushwoosh', defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', autoSubscribe: true, subscribeWidget: { enable: false }, userId: 'user_id' }]);</script>