Docs

PWA y Web Push

Una landing PWA es una landing local que Orbitra convierte en una web app completa: una vidriera de "app store", un manifest y un service worker. Combinada con el módulo Web Push te deja cultivar una base de suscriptores justo en la vidriera y enviarles pushes — todo por tu cuenta, sin servicios externos (FCM se usa solo como transporte de Android, Apple como el de iOS; las claves y la base de datos son tuyas).

Este documento cubre: el constructor de PWA, la instalación de la app, la vinculación de dominio, la instrumentación del embudo, la base de suscriptores, los mensajes (manuales y por evento), el cron de entrega y la solución de problemas.


1. Landing PWA: qué es y cómo funciona

1.1 Cómo funciona por dentro

1.2 El constructor

Landings → Add PWA (o "Duplicate" sobre una existente). Los bloques principales del editor:

BloqueQué configura
GeneralNombre de la app, slug, grupo, icono y capturas (vía la Content Gallery), categoría, desarrollador, idioma, versión, "updated"
StoreDescripción (con macros {value}), etiquetas, histograma de valoración, reseñas, "what's new", badges (verificado, brillo, contador en vivo), tema claro/oscuro, esquema de colores
ScreenLa pantalla in-app que se muestra tras la instalación: tipo, título, texto, botón, imagen, HTML/JS personalizado
ActionsAcción del botón de instalación: a la oferta / a una campaña / a una URL / a ningún lado (action_target), temporizadores de auto-redirect
PushActivar la suscripción push en la pantalla de la app (push_enabled)
DomainVinculación de dominio (ver §2) + la oferta para el dominio directo
ReadinessUna checklist en vivo de cómo se verá la hoja de instalación nativa: icono, descripción, tamaños de capturas, claves push, vinculación de dominio

El botón Preview renderiza el borrador de la configuración con el renderer de producción — una vista previa en vivo de la vidriera y la pantalla (plataforma auto/iOS) sin guardar.

1.3 El embudo y los beacons

La página de la vidriera envía beacons de un píxel que escriben en el clic:

Todas las columnas son visibles en los detalles del clic — la herramienta principal de diagnóstico del embudo: el tracker nombra el motivo él mismo, sin necesidad de logs del navegador.

1.4 La suscripción push vive en el service worker

La suscripción corre por completo dentro del sw.js generado (orbitraSubscribe): la página solo manda un mensaje al worker y sale hacia la oferta. Esto es deliberado — en iOS el primer pushManager.subscribe en frío puede tardar decenas de segundos, y la suscripción no debe depender de cuánto se queda el usuario en la página. El worker además:

El placeholder {vapid_public} en sw.js se sustituye al momento de servir el archivo, no al generarlo — un cambio de clave VAPID llega a las apps ya instaladas sin regenerar los archivos estáticos.

1.5 RENDERER_VERSION

Cada cambio del renderer sube RENDERER_VERSION (core/PwaLanding.php). En la próxima vista de la landing el tracker compara el marcador de versión en los archivos estáticos renderizados y regenera él solo los desactualizados — sin re-subir nada al servidor a mano.


2. Vinculación dominio → PWA

Un dominio se puede vincular a una PWA directamente: una visita a https://domain.com/ abre la vidriera desde la raíz, sin salto por una campaña ni por /lander/ — una URL de instalación limpia.


3. Web Push: la base, las claves, el envío

3.1 Claves VAPID y el contacto

La página Push Base (panel → Push):

  1. Rellena el contacto — mailto:[email protected] o https://…. Sin un contacto real la generación de claves está bloqueada: Apple (web.push.apple.com) valida el claim sub del JWT y responde 403 BadJwtToken a direcciones de relleno.
  2. Pulsa Generate keys. Las claves se guardan en los ajustes del tracker (vapid_public_key / vapid_private_key / vapid_private_pem); el cifrado y la firma son PHP + openssl puros (RFC 8291 + RFC 8292), sin composer.
  3. La rotación de claves pide confirmación: las suscripciones existentes dejan de ser válidas, pero cada dispositivo se re-suscribe en silencio en la próxima apertura de la app (self-heal); la base se restaura sola.

La franja de diagnóstico de la página muestra: si existen las claves, la clave pública, el contacto (con una advertencia si está el de por defecto), la antigüedad del último ping del worker y los últimos códigos de error de entrega.

3.2 La pestaña "Subscribers"

La tabla push_subscriptions: id, clic, endpoint, país, idioma, UA, estado (active / expired), creado, última muestra. Capacidades:

Los suscriptores se multiplican con reinstalaciones y re-suscripciones (el endpoint lo cambia el servicio push) — las filas viejas expiran solas vía 404/410 al enviar, sin limpieza aparte. Antes de un envío masivo, comprueba la "frescura" de un suscriptor por su clic (los detalles del clic muestran la landing y la UA de instalación).

3.3 La pestaña "Messages"

Los mensajes son plantillas de difusión. Dos clases:

Campos del mensaje: título (≤250), cuerpo (≤400), icono (una URL, convenientemente de la Gallery), imagen de banner (una URL — Chrome de Android la muestra como una imagen grande en la notificación; iOS la ignora en silencio), enlace de destino, segmento, targeting de país e idioma, la flag "active".

Los segmentos se calculan a partir de los contadores de conversión del suscriptor en el momento de encolar:

SegmentoQuién lo recibe
alltodos los suscriptores activos
reg0sin registro
reg1dep0registrado, sin depósito
reg1dep1registrado y con depósito

El targeting (migración 60) estrecha cualquier segmento aún más al encolar: countries — una lista de códigos ISO separados por comas que se coteja con el geo del suscriptor (US, DE), languages — códigos de idioma de navegador de 2 letras que se emparejan por subtag primario (en coincide con un suscriptor guardado como en-US). Lista vacía = sin restricción. Las entradas basura se descartan al guardar, nunca se almacenan.

El cuerpo soporta macros que se expanden al momento del envío: {variant1|variant2} (elección aleatoria, anidación ≤10), {Random=(X,Y)}, {subid} y otras macros de clic — un mensaje le da a cada destinatario su propio texto.

3.3.1 Clics de push y el CTR del mensaje

Cada notificación que el SW muestra lleva los ids de entrega en su data (subid, message_id, sid). Tocarla dispara un beacon (/pixel.gif?action=pwa&kind=pushclick) antes de la navegación, así que el toque se cuenta aunque el navegador salga de inmediato hacia la oferta:

3.3.2 Darse de baja

La notificación en sí lleva un botón de acción Unsubscribe (localizado, horneado en el SW de la landing; iOS ignora las acciones — tocar la notificación allí igual abre). Pulsarlo hace POST del endpoint del navegador al ingest público /push_unsubscribe, que pone is_active = 0 (idempotente; las claves se quedan, así que el panel puede reactivar). También hay una página pública independiente /push-unsubscribe?endpoint=<urlencoded> — muestra un botón de confirmación (la desactivación es un POST detrás de él, así que un enlace precargado nunca da de baja a nadie) y se puede enlazar desde cualquier parte.

El SW generado también sirve una página offline dedicada para las navegaciones fallidas (localizada, con un botón Retry) en lugar de la vidriera cacheada vieja — una página de tienda cacheada mandaría un beacon con un click id viejo y su CTA no puede funcionar offline de todos modos.

3.4 El envío: la cola y el cron

El panel en sí no envía nada. El botón "Send now" en la fila de un mensaje encola (push_queue) una entrada por suscriptor activo del segmento, con protección de duplicados, y responde "Queued: N".

La entrega la hace el worker del cron cli/push_cron.php — cada minuto:

* * * * * www-data php /var/www/orbitra/cli/push_cron.php --quiet >> /var/www/orbitra/var/logs/push.log 2>&1

La línea la instala install.sh automáticamente (marcador # orbitra-push); comprobar: crontab -u www-data -l | grep orbitra-push. El worker: flock contra ejecuciones paralelas, lotes ≤300, reintento tras 300 segundos, 429 respeta Retry-After, 401/403 — un reintento con un JWT fresco, 404/410 — la suscripción expira, 5xx/red — de vuelta a la cola. Los mensajes por evento los dispara el mismo worker vía un cursor en los ajustes.

La salud de la cola se muestra en la franja encima de la lista de mensajes: pending/done/failed y la hora del último ping del worker. Si el ping no avanza — el cron no está instalado o no corre, y la entrega no ocurrirá.

3.5 Qué significa "enviado"

Un 201 del servicio push significa "sobre aceptado", no entregado. El servicio push no puede romper el cifrado (E2E): responde 201 y descarta el mensaje en silencio si el dispositivo nunca lo lee. El juez final es solo el teléfono. Una cadena de verificación monitorizada:

  1. Push Base → Subscribers → Send en la fila → el banner de "aceptado";
  2. en el dispositivo: la bandeja de notificaciones (el banner puede haber pasado en silencio mientras la app estaba abierta);
  3. si 201 pero silencio — ver §4.

4. Solución de problemas y casos comunes

Ninguna suscripción — detalles del clic: push_fail_reason nombra el motivo (unsupported = sin Push API — el webview de Telegram/Chrome en iOS; insecure = sin HTTPS; nokey = VAPID sin configurar; denied = rechazado; timeout = red lenta — la suscripción llegará en la próxima apertura vía self-heal).

iOS — solo Safari, y solo desde la pantalla de inicio. El web push en iOS funciona bajo estas condiciones: iOS ≥ 16.4, la app añadida a la pantalla de inicio específicamente desde Safari (el Safari normal no tiene objeto Notification — nunca se crea una suscripción), un dominio con certificado público en regla. Una app añadida a la pantalla de inicio desde Chrome (CriOS) no tiene garantía de push: comprueba el navegador de instalación por la UA en los detalles del clic (CriOS/… = Chrome, Version/… = Safari). Si no funciona — reinstala el icono desde Safari.

403 BadJwtToken al enviar — un contacto VAPID inválido: Apple rechaza direcciones de relleno (mailto:orbitra@localhost). Pon un mailto: real.

201 pero no llega para todos ni en todas partes — comprueba que el servidor esté en la última versión (git log --oneline -1 vía sudo -u www-data): las builds tempranas tenían defectos de sobre criptográfico (una cabecera sin keyid, un key schedule no conforme a RFC 8291) que el servicio igualmente aceptaba con un 201. Luego un experimento de control: Chrome de escritorio → instala la PWA → Allow → Send: si llega al escritorio pero no al iPhone — el problema es el dispositivo/canal (una VPN rompe la conexión persistente de APNs; instala por Chrome); si el escritorio tampoco recibe nada — escribe a soporte con el código de error de la franja de diagnóstico.

"Los botones no clickean" tras una actualización del panel — casi siempre la caché del navegador con un index.html viejo: recarga dura (Cmd+Shift+R) o una pestaña privada.

Cron en silencio — push_cron_last_ping_at no avanza: el cron no está instalado. crontab -u www-data -l | grep orbitra-push; el log es var/logs/push.log.


5. Tests

Salir del navegador in-app (renderer v19+)

Una PWA no se puede instalar dentro del webview de FB/IG/TikTok — cada visita en webview es una pérdida de embudo garantizada. Con Auto-open in browser activado (por defecto), la landing sale de inmediato: Android vía un intent:// hacia Chrome (la URL actual como fallback), iOS 17+ vía x-safari-https://; el iOS más viejo se queda con la tarjeta de instrucciones. La URL de escape lleva el click id, y el navegador externo continúa el mismo clic — sin segundo clic, sin embudo partido. La tarjeta de embudo de la PWA muestra intentos y tasa de éxito (retornos en un navegador real). Únicamente el lado del dinero escapa: una página segura sigue sirviendo el contenido seguro.

Entrega y atribución de conversiones

Macros de oferta en el texto del push

{offer.value} / {offer.value1} / {offer.value2} se resuelven desde la tabla por país de la oferta (Country → bonus / freespins / moneda; país vacío = fallback universal) según el país del suscriptor, a través de la oferta a la que fue el clic de la suscripción. El editor de mensajes tiene una vista previa en vivo para un país + oferta elegidos. Sin contexto la macro se queda visible — nunca en blanco en silencio.

Envío a la hora local del suscriptor

La suscripción guarda la zona horaria IANA del dispositivo (filas viejas: derivada del país del geo). Un mensaje con Send at subscriber's local time espera las horas de silencio — por defecto 23:00–08:00 locales (push_quiet_hours) — y envía en el primer minuto permitido. La re-encola mantiene la fila pendiente (last_code=quiet), nunca falla.

Las notificaciones push del propio operador (PWA del panel)

Todo lo anterior hace push a suscriptores de landings. El panel en sí también es una PWA (instalable desde el navegador), y Users & Profile → Profile → Push notifications permite al operador recibir web push en sus propios dispositivos — alertas de conversiones y digests por día/semana/mes — sin necesidad de Telegram.

Digests semanales/mensuales de Telegram (migración 70)

El resumen diario del bot de admin creció dos hermanos, en la página Notifications → Telegram: semanal (la última semana completa, enviado el lunes) y mensual (el último mes completo, enviado el día 1); solo la hora de envío es configurable. Todas las horas de Telegram — el diario incluido — se leen en la zona horaria del perfil del primer admin, no en la hora del servidor. Los toggles por chat reflejan los comandos del bot /weekly on|off y /monthly on|off; la entrega una vez por ventana queda bloqueada por tg_digest_log (chat × periodo × ventana únicos). Los totales vienen del mismo helper AdminPushNotify::digestWindow()/windowStats() que usan los digests push, así que Telegram y push nunca pueden discrepar en los números.

← Anterior
Landing pages (referencia)
Siguiente →
Embudo de PWA
Ver el código en GitHub: github.com/fenjo26/Orbitra.link/wiki
Todas las guías
Docs

Inicio rápido: tu primera campaña

El camino corto: instala el tracker, crea la red, la oferta y la campaña, y consigue tus primeros clics y conversiones en menos de una hora.

Leer la guía →
Docs

Instalación y actualizaciones

Instala Orbitra en un servidor Ubuntu o Debian recién creado con un solo comando, actualiza PHP y las versiones nuevas de forma segura.

Leer la guía →
Docs

Migrar desde Keitaro

Mueve campañas, ofertas, fuentes y dominios de Keitaro a Orbitra con un dump SQL — qué se transfiere y qué revisar después.

Leer la guía →
Docs

Migrar desde Binom

Mueve campañas y flujos de Binom v2 a Orbitra vía su Public API — qué se transfiere automáticamente y qué se ajusta a mano.

Leer la guía →
Docs

Resumen de funciones

Todo lo que Orbitra puede hacer: campañas y flujos, cloaking, landings, PWA, postbacks, costos, informes e integraciones.

Leer la guía →
Docs

Campañas y flujos

La referencia completa: ajustes de campaña, tipos de flujo, esquemas, rotación, filtros, test links y cada opción explicada.

Leer la guía →
Docs

Cloaking: referencia completa

Referencia completa del cloaking: capas de detección, sensibilidad, ajustes globales, veredictos, motivos e informes.

Leer la guía →
Docs

Browser check

Cómo el check JS atrapa bots, VMs y emuladores por contradicciones del navegador: modos Off / Observe / Soft / Strict y sus signos.

Leer la guía →
Docs

Landing pages (referencia)

Tipos de landing, la macro {offer}, el adaptador JS, LeadForge y landings multi-oferta — la referencia completa.

Leer la guía →
Docs

PWA y Web Push

Crea apps PWA instalables y tu propia base de suscriptores push: constructor, claves VAPID, mensajes, atribución y solución de problemas.

Leer la guía →
Docs

Embudo de PWA

Cómo funciona el embudo configurable de una PWA: pasos y tipos de pantalla, tracking por pantalla, estadísticas del embudo y vista previa en el editor.

Leer la guía →
Docs

Popups de conversión

Muestra conversiones reales como popups en tus landings: activación por campaña, plantillas por vertical, disparadores y ubicación.

Leer la guía →
Docs

Grabaciones de sesión y mapas de calor

Reproduce visitas reales y consulta el mapa de calor de clics y de scroll. Límites de almacenamiento y notas de privacidad.

Leer la guía →
Docs

Content Gallery (referencia)

Almacenamiento central de iconos, capturas y creativos usados en PWAs y landings: carpetas, límites y el MediaPicker en los editores.

Leer la guía →
Docs

Biblioteca de creativos

Almacena creativos con tracking de subid y pruébalos en distintas campañas: métricas por creativo sincronizadas con Facebook y TikTok.

Leer la guía →
Docs

PWA externas y canales de Telegram

Publica PWAs en dominios externos y usa canales de Telegram como fuente de tráfico con suscriptores atribuidos.

Leer la guía →
Docs

Postbacks y conversiones

Postbacks entrantes, estados y tipos de conversión, y postbacks S2S salientes hacia tu fuente de tráfico.

Leer la guía →
Docs

Costos

Importa el gasto de Facebook, TikTok y Google Ads, o actualízalo por API y cron — y cómo funciona el agregador de ingresos.

Leer la guía →
Docs

Redes push y pop

Trabajo con fuentes de tráfico push y pop: importación de gasto por campaña y zona, optimización de zonas y el Zone Killer.

Leer la guía →
Docs

Facebook / Meta

Importación de costos desde Meta Ads y Conversions API: eventos del lado del servidor con deduplicación.

Leer la guía →
Docs

Dolphin / Fbtool

Recibe los costos de Facebook vía la API de Dolphin (Fbtool) en tiempo real: clave de API, configuración de cada servicio y cómo se reparte el gasto entre los clics.

Leer la guía →
Docs

FB Comment Cleaner

Modera en bloque los comentarios bajo tus anuncios de Meta: ocultar, borrar y filtrar por palabras clave, con dry run, journal y auto-pausa.

Leer la guía →
Docs

Fuentes de tráfico y redes de afiliados

Los dos directorios que configuran los bordes del embudo: plantillas y parámetros de fuentes y redes, postback global, macros de oferta y LeadForge.

Leer la guía →
Docs

Informes, logs y métricas

El constructor de informes, tendencias y cohortes, el log de tráfico y la tarjeta del clic, más la definición de cada métrica.

Leer la guía →
Docs

Dominios y SSL

Añade dominios, apunta el DNS y emite certificados Let's Encrypt gratis: ajustes del dominio, modos SSL, registrars conectados y Backorder.

Leer la guía →
Docs

Cloudflare

Cómo pasar los dominios de campaña por Cloudflare vía API: token, parking automático del registro A, modos SSL de zona y proxy.

Leer la guía →
Docs

Administración

Usuarios, roles y permisos, ajustes de seguridad y privacidad, bases de datos geo, actualizaciones y estado del sistema.

Leer la guía →
Docs

Bot de Telegram

Gestiona el tracker desde Telegram: estadísticas, conversiones y alertas en el chat, con webhook o polling.

Leer la guía →
Docs

MCP: un asistente de IA en el tracker

Conecta Claude o cualquier cliente MCP a Orbitra y maneja campañas con comandos en lenguaje natural: claves de API, conexión y seguridad.

Leer la guía →