Saltar al contenido
Guías de usuarioSoporte Solicitar demo Iniciar sesión
Pushwoosh.com

Web push SDK 3.0

Integración

Anchor link to

Ejemplo de integración en GitHub

Obtén el SDK de Web Push de Pushwoosh y descomprímelo. Deberías tener los siguientes archivos:

Anchor link to
  • pushwoosh-service-worker.js

Coloca todos estos archivos en el directorio raíz de nivel superior de tu sitio web.

Anchor link to

Inicializa el SDK:

Anchor link to
  1. Incluye 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>
  1. Inicializa el Web Push SDK y asegúrate 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 tu 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 tu Portal de Desarrollador de Apple. Solo es necesario si envías 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 una 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, establece un ID de usuario personalizado
    tags: {
        'Name': 'John Smith'     // opcional, establece Tags personalizados
    }
}]);
</script>

Web popups

Anchor link to

Añade webPopups a tu objeto init para habilitar las campañas de Web popup en tu sitio.

webPopups: {
  enable: true,
},

Las campañas de Web popup muestran superposiciones que configuras en el Panel de Control, como promociones, anuncios o formularios de captación de leads. A diferencia del popup de suscripción personalizado (subscribePopup), que solo gestiona la suscripción a notificaciones push web, las campañas de Web popup pueden mostrar cualquier contenido que configures. Para la configuración en el Panel de Control, consulta Entendiendo los Web popups.

Botón de suscripción a notificaciones push

Anchor link to

Para animar a tus usuarios a suscribirse a las notificaciones push, recomendamos implementar un botón de suscripción a notificaciones push en tu sitio web. ¡Mejora la experiencia del usuario y consigue más suscriptores!

Configuración

Anchor link to

Para terminar de implementar las notificaciones push en tu sitio web, necesitas configurar las plataformas web en tu Panel de Control de Pushwoosh siguiendo nuestras guías paso a paso:

Registrar el service worker en un ámbito diferente

Anchor link to

A veces no puedes colocar el archivo del service worker en un directorio raíz de un sitio web, sino en un subdirectorio.

En este caso, modifica 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 to

En el Web SDK 3.0 de Pushwoosh puedes suscribirte a ciertos eventos para rastrearlos**,** o darte de baja de eventos si ya no necesitas rastrearlos.

Para rastrear la carga del Web SDK 3.0, dispara el evento onLoad de la siguiente manera:

// Evento de carga
Pushwoosh.push(['onLoad', (api) => {
  console.log('¡Pushwoosh cargado!');
}]);

Para rastrear la inicialización correcta del Web SDK, dispara el evento onReady:

// Evento Ready
Pushwoosh.push((api) => {
  console.log('¡Pushwoosh listo!');
});

Para suscribirte o darte de baja de cualquiera de los eventos del SDK, utiliza los manejadores después de la carga del SDK:

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Evento disparado: event-name!');
  }


  // Para suscribirte a un evento:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // Para darte de baja de un evento:
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

Eventos del SDK

Anchor link to

Evento de suscripción

Anchor link to

Se 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 to

Se ejecuta después de que un dispositivo es dado 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 to

Rastrea 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 to

Rastrea 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 to

Comprueba el estado del permiso de notificaciones push en la inicialización del SDK; rastrea la actualización de este estado cada vez que tenga lugar.

Pushwoosh.push(['onLoad', (api) => {
  // Se ejecuta durante la inicialización del SDK si 'autoSubscribe: false' o/y 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 to

Rastrea la entrega de una notificación 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 to

Rastrea si una notificación push es abierta o cerrada por un usuario.

Pushwoosh.push(['onLoad', (api) => {
  // Se ejecuta cuando un usuario hace clic en una 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 to

Rastrea 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 es recibido y guardado en indexedDB.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Evento disparado: receive-inbox-message', payload.message);
  });


  // Ejecutado después de que la Bandeja de Entrada se actualiza automáticamente mientras la página se está cargando.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Evento disparado: receive-inbox-message', payload.messages);
  });
}]);

Eventos del popup de suscripción personalizado

Anchor link to

Para detalles sobre el manejo de eventos del popup de suscripción personalizado, por favor consulta la Guía de Eventos del Popup de Suscripción Personalizado.

API

Anchor link to

Después de que el Web Push SDK se inicialice, puedes hacer 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 email 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, registrar múltiples usuarios 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 to

Mé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: Email 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 a 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('Multi-registro exitoso:', response);
  })
  .catch((error) => {
    console.error('Fallo en el multi-registro:', error);
  });
});

Tipos de plataforma:

  • TPlatformSafari (10): Plataforma Safari
  • TPlatformChrome (11): Plataforma Chrome
  • TPlatformFirefox (12): Plataforma Firefox

Tipos de operación de Tag:

  • TTagOperationSet (0): Establecer valor de tag (reemplazar valor existente)
  • TTagOperationAppend (1): Añadir a 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: Soporta 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 el valor de un Tag

Anchor link to

Para incrementar un valor de un Tag numérico, utiliza 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 a un Tag

Anchor link to

Para añadir nuevos valores al Tag de tipo Lista existente, utiliza 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 un Tag

Anchor link to

Para eliminar un valor de un Tag de tipo Lista, utiliza 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 to

Pushwoosh.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.

Llama a este método si has 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()

  1. Se ejecuta el método /unregisterDevice.
  2. 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 true/false.

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/false

Métodos de InboxMessages

Anchor link to

messagesWithNoActionPerformedCount(): 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 marca el mensaje 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');
  });

Soporte para Progressive Web App

Anchor link to

Para integrar Pushwoosh en tu Aplicación Web Progresiva (PWA), sigue los pasos que se describen a continuación.

1. Copia la ruta a tu archivo de Service Worker:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- la url de tu service worker
  });
}

Luego, utiliza 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 tu 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 re-suscripción),
  • cuando se elimina un token de push (al eliminar un dispositivo de la base de usuarios).

Esto acelera la carga de tus páginas al reducir el número de solicitudes al servidor.

Los navegadores no permiten que dos Service Workers diferentes se registren al mismo tiempo (lee más en: https://github.com/w3c/ServiceWorker/issues/921), por lo que para que tu PWA funcione correctamente, se debe registrar un Service Worker común para tu base de código y la base de código de Pushwoosh.

2. Añade la siguiente cadena a tu Service Worker (al principio o al final, no importa):

importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);

Así habilitas la recepción y el procesamiento de notificaciones push enviadas a través de los servicios de Pushwoosh para tu Service Worker.

Instalación desde Google Tag Manager

Anchor link to

Usa el siguiente código en tu Google Tag Manager para inicializar el SDK de Pushwoosh. Crea una etiqueta HTML personalizada y pega el código a continuación. Asegúrate de cambiar tu 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 establece una prioridad alta de activación de la etiqueta (ej: 100) y actívala en Todas las páginas. Ve la captura de pantalla a continuación.

<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>