Funcionamiento del seguimiento¶

Arquitectura de doble canal¶

Cada evento de seguimiento se dispara a través de dos canales simultáneamente:

1. API de Conversiones (CA) — PHP/lado del servidor, enviado directamente a la Graph API de Facebook mediante el SDK de Facebook Business. Se dispara dentro de los hooks de PS, inmediatamente en la solicitud HTTP que lo origina.
2. Facebook Pixel (JS) — llamadas fbq() del lado del navegador, inyectadas mediante un script frontend compilado con Vite. El script sondea el servidor en busca de eventos en cola y los dispara con fbq().

Ambos canales llevan el mismo event_id para que Facebook los deduplique automáticamente.

Flujo de eventos¶

1. Se dispara un hook de PS (p.ej. actionCartUpdateQuantityBefore)
   └── CAEventBuilder::addToCart() construye el evento
       ├── Establece event_name, event_time, event_id (UUID), event_source_url, user_data, custom_data
       └── CAEventBuilder::sendEvent()
           ├── Envía el evento a la Graph API de Facebook (canal CA)
           └── Persiste la fila FbpEvent en la tabla fbp_event
               ├── ca_sent = 1
               ├── js_sent = 0
               └── js_event = payload JSON para la llamada fbq() del lado del navegador

2. El navegador carga la página, el JS frontend se inicia
   └── Sondea ConsumerController (?action=poll)
       └── Devuelve: { pixel: { pixel_id, external_id }, events: [ { id, event_type, js_event } ] }
           └── Para cada evento:
               ├── fbq('track', event_type, js_event_data)  ← dispara el píxel
               └── Llama a ConsumerController (?action=confirm&id_fbp_event=N)
                   └── Marca fbp_event.js_sent = 1

Contexto del invitado¶

En cada inicialización del front controller (actionFrontControllerInitAfter), el módulo captura:

• User agent — $_SERVER['HTTP_USER_AGENT']
• IP del cliente — mediante Tools::getRemoteAddr()
• Cookie _fbp — ID de navegador de Facebook, persistente entre sesiones
• Cookie _fbc — ID de clic de Facebook, establecido cuando un usuario llega mediante un anuncio de Facebook

Estos valores se almacenan en fbp_guest_context con la clave id_guest y se adjuntan al user_data de cada evento CA. Si el usuario está autenticado, el nombre, el correo electrónico y la fecha de nacimiento también se hashean e incluyen.

Remapeo de ID de invitado¶

PrestaShop puede renovar id_guest durante el pago (p.ej. al crear el pedido). Cuando esto ocurre, los eventos en cola bajo el ID de invitado antiguo nunca serían sondeados por el navegador (que ahora tiene el nuevo id_guest).

El módulo gestiona esto en dos lugares:

1. hookActionFrontControllerInitAfter — si se ve _fbp asociado con un id_guest diferente, los eventos pendientes para el invitado obsoleto se remapean al invitado actual.
2. ConsumerController::remapStaleGuestEvents() — una red de seguridad: ejecuta la misma lógica de remapeo antes de la consulta de sondeo, capturando los casos en que la renovación ocurrió después de que se disparara el hook.

Formato del ID de producto¶

El ID de producto usado en los eventos de seguimiento sigue los indicadores de formato de ID (cs_id_format) y usar referencia (cs_use_reference_id) de la configuración del píxel:

• Predeterminado: {id} → "42" (ID de producto) o "42-7" (ID de producto + ID de combinación cuando se exportan combinaciones)
• Plantilla personalizada: p.ej. ps_{id} → "ps_42"
• Modo de referencia: {ref} → valor del campo de referencia del producto

Esto debe coincidir con lo que usa la exportación del catálogo, para que los eventos de seguimiento referencien los mismos IDs que el feed.

Deduplicación¶

A cada evento se le asigna un event_id único (generado por Utilities::createEventId()). El mismo ID se usa tanto para el evento CA como para el evento JS del píxel almacenado en fbp_event.event_id. Facebook lo usa para deduplicar.

Tabla fbp_event¶