Referencia del Browser SDK
Una referencia del Browser SDK, window.sdk: cómo ofrecer la instalación de una PWA desde la página, suscribir al visitante a push, enviar eventos y qué configuración necesita para ello. Para una introducción general, consulte Browser SDK; para conectarlo a su propio prelanding, consulte SDK en su prelanding.
La configuración de window.pwaConfig
El SDK lee su configuración desde el objeto window.pwaConfig, que usted establece en la página antes de la etiqueta del script. En las páginas servidas por Qubix, el objeto se rellena automáticamente; en su propio prelanding lo configura usted mismo.
| Campo | Propósito |
|---|---|
pwaId | El identificador de la PWA. Necesario para la instalación y para el push |
domain | El dominio de la página. Necesario para el manifiesto y para el push |
vapidKey | La clave para el push. Normalmente se incluye automáticamente cuando se carga /sdk.js — no es necesario establecerla manualmente |
offerId | La oferta (si necesita pasarla explícitamente) |
campaignId | La campaña (si necesita pasarla explícitamente) |
params | Etiquetas de seguimiento adicionales |
previewMode | Modo de vista previa: los eventos no se envían |
El identificador de la PWA (pwaId) se obtiene de la tarjeta de la aplicación en la sección Aplicaciones PWA.
Suscribirse a push
sdk.subscribePush() pide al navegador permiso de notificaciones y crea una suscripción. Debe llamarse explícitamente — por ejemplo, al hacer clic en un botón. No se activa por sí solo.
const subscription = await sdk.subscribePush()
if (subscription) {
// el visitante permitió las notificaciones y está suscrito
}
Qué ocurre internamente:
- Se muestra el mensaje de permiso del navegador.
- Si el visitante lo permite, se crea una suscripción y se envía a Qubix.
- Las llamadas repetidas son seguras: si el visitante ya está suscrito, el mensaje no se vuelve a mostrar.
No es necesario instalar la aplicación para el push: un visitante puede suscribirse en una página ordinaria.
El push solo funciona sobre una conexión segura (HTTPS) y en un dominio configurado en Qubix. Más información en SDK en su prelanding.
Instalar la PWA
Si window.pwaConfig tiene un pwaId, el SDK expone los métodos sdk.pwa:
| Método | Qué hace |
|---|---|
sdk.pwa.init() | Preparación: registra el service worker y adjunta el manifiesto de la aplicación |
sdk.pwa.install() | Muestra el mensaje de instalación de la aplicación del sistema |
sdk.pwa.canInstall() | Si la instalación está disponible en este momento |
sdk.pwa.isInstalled() | Si la aplicación ya está instalada |
sdk.pwa.open() | Abrir la aplicación instalada |
init, install e isInstalled son asíncronos — llámelos con await. canInstall y open devuelven un valor de inmediato.
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
El mensaje de instalación lo muestra el propio navegador, por lo que se aplican sus reglas: HTTPS, un manifiesto adjunto (el SDK lo adjunta por usted) y normalmente una acción del visitante en la página (un clic, un desplazamiento). Por eso el botón de instalación se asocia habitualmente a un toque explícito.
Eventos
El SDK informa a la analítica de los momentos clave de forma autónoma — son visibles en los informes y en el flujo de eventos:
| Evento | Cuándo |
|---|---|
campaign_visit | Una visita a la página (se envía automáticamente) |
push_prompt_shown | Se mostró el mensaje de permiso de push |
push_allow | El visitante permitió el push |
push_deny | El visitante denegó el push |
push_ignored | El visitante descartó el mensaje sin elegir |
install_accepted | El visitante aceptó instalar la aplicación |
install_rejected | El visitante rechazó la instalación |
Puede enviar su propio evento de forma manual:
sdk.sendEvent('my_button_click', { place: 'hero' })
Datos de tráfico
Métodos auxiliares para leer el contexto del clic:
| Método | Devuelve |
|---|---|
sdk.getOffer() | La oferta actual (id y URL) |
sdk.getPwa() | La PWA actual |
sdk.getPiuid() | El identificador del visitante |
sdk.getTrackingParams() | Las etiquetas del rastreador que llegaron con el clic |
sdk.buildOfferUrl(url) | Construir una URL de oferta con las etiquetas transferidas |
sdk.showStore() | Ir a la tarjeta de la tienda de la PWA |
Qué hace el SDK por sí solo
Sin ninguna llamada de su parte, al cargar la página el SDK recopila datos del dispositivo, analiza las etiquetas de seguimiento de la URL, adjunta el manifiesto de la aplicación (si pwaId está configurado) y envía el evento campaign_visit. La suscripción a la instalación y al push no se inician por sí solos — usted los activa desde el código.