Módulo Google Analytics 4 para PrestaShop: compras por API

Instrucciones de conexión

Qué hace la conexión de GA4

Envía el evento purchase desde PrestaShop mediante Measurement Protocol, asociado al client_id y session_id de la visita. La confirmación de compra puede enviarse aunque el comprador no vuelva de PayPal o use un checkout exprés. Mantén la etiqueta de GA4 para recoger navegación y sesión.

Configurar Google Analytics 4

1. Abre GA4 → Administrar → Flujos de datos y selecciona el flujo web de la tienda. Copia el ID de medición G-…; no uses el ID numérico de la propiedad.
2. En ese mismo flujo, abre Secretos de la API de Measurement Protocol → Crear, acepta los avisos que correspondan y crea un secreto para NDC PrestaShop.
3. Pega el ID y el secreto en el módulo. El secreto se guarda en servidor y no se expone al navegador. Para esta conexión no se necesita OAuth ni un CRM.
4. Conecta el consentimiento y conserva la etiqueta GA4. Si tu instalación dispone de gtag, el módulo consulta los identificadores mediante su API oficial get después del consentimiento.
5. Si GTM no expone gtag, configura un puente con las variables oficiales de ID de cliente y de sesión de Analytics. Entrega ambos valores en window.NDCTrackingIds y dispara ndc:identifiers según el ejemplo siguiente. No generes IDs nuevos al producirse el pago.
6. Usa el mismo transaction_id que la compra del navegador y evita dos implementaciones independientes que envíen compras con IDs diferentes. La deduplicación debe validarse con el mismo visitante, sesión e identificador de compra.
7. Programa el cron y prueba en validación. El endpoint de validación comprueba parámetros, pero no registra ventas en informes ni acredita recepción real.
8. Después, pasa a producción con una compra nueva y comprueba el evento, la transacción y su origen/campaña en GA4. No dejes dos acciones primarias de compra en Google Ads si importas GA4 y usas a la vez el módulo directo de Ads.

// Dentro de GTM o de la integración de la etiqueta, con consentimiento:
window.NDCTrackingIds = {
  client_id: ID_CLIENTE_GA4_REAL,
  session_id: ID_SESION_GA4_REAL
};
window.dispatchEvent(new Event('ndc:identifiers'));

Los nombres en mayúsculas son marcadores. Sustitúyelos por valores reales obtenidos de Analytics; no por el email ni por el ID del cliente de PrestaShop.

Importes y atribución

value contiene los productos netos sin IVA, envío ni envoltorio. Se descuentan los descuentos del carrito, distribuyéndolos entre los artículos. tax y shipping se envían por separado. Los artículos incluyen ID del producto y combinación, precio neto y unidades. Esta versión admite hasta 200 líneas y no envía datos personales como email o teléfono.

El envío debe ser inmediato tras el pago. GA4 limita la antigüedad del evento a 72 horas; el módulo expira a las 70 horas para evitar modificar artificialmente fechas. La unión a una sesión tiene requisitos temporales adicionales: Google recomienda recibir los eventos dentro de 48 horas del evento del navegador y la atribución de sesión puede exigir ventanas más estrictas. En pagos por transferencia o contra reembolso varios días después no se garantiza recuperar la campaña de la visita.

Measurement Protocol complementa el etiquetado. Si no se capturaron el consentimiento o los identificadores antes del checkout exprés, el módulo bloquea el envío en lugar de inventar la sesión. No recupera automáticamente pedidos históricos que carezcan de estos datos.

Antes de instalar

Necesitas acceso de administrador a PrestaShop, una copia de seguridad y un entorno de pruebas. Objetivo de compatibilidad: PrestaShop 1.7.8, 8 y 9, con PHP 7.4 o posterior compatible con la versión de la tienda, cURL y OpenSSL. No está certificado todavía en esas instalaciones. Puede coexistir con el otro módulo NDC y no modifica el checkout.

El proveedor de pago debe crear el pedido, vincularlo a su carrito y actualizar su estado en PrestaShop. Esta versión no sustituye el módulo de PayPal, InstantPay o financiación ni recibe sus webhooks directamente.

Instalación en PrestaShop

1. En Módulos → Gestor de módulos → Subir un módulo, carga el ZIP instalable individual. No subas el paquete general de publicación.
2. Abre Configurar. En multitienda, selecciona una tienda concreta y configura cada tienda por separado.
3. Rellena los datos de conexión siguiendo el apartado específico de esta guía. Empieza con Validación.
4. Ajusta transaction_id al formato EXACTO enviado por la etiqueta actual. Se admiten {order_id}, {reference} y {shop_id}. El valor por defecto es NDC-{shop_id}-{order_id}.
5. Conecta y prueba el consentimiento. Marca la confirmación de configuración solo después.
6. Comprueba los estados pagados. Se usan los estados con la propiedad nativa «pagado». Añade IDs de otros estados únicamente si confirman realmente el pago o la financiación garantizada. No añadas estados de autorización o espera.
7. Programa el cron, activa el módulo y realiza compras de prueba. Revisa el registro de últimos pedidos.

Consentimiento: paso obligatorio

El módulo se inicia con consentimiento denegado. No detecta ni configura automáticamente cualquier banner. Tu técnico debe conectar el evento de la CMP mediante el siguiente puente. Este puente no sustituye Consent Mode ni cambia las preferencias de Google Tag Manager.

// Ejecutar al cargar la CMP y en cada cambio de preferencias.
// Los cuatro valores deben proceder de la elección REAL del visitante.
const estadoReal = {
  analytics_storage: cmpPermiteAnalitica ? 'granted' : 'denied',
  ad_storage: cmpPermitePublicidad ? 'granted' : 'denied',
  ad_user_data: cmpPermiteDatosPublicidad ? 'granted' : 'denied',
  ad_personalization: cmpPermitePersonalizacion ? 'granted' : 'denied'
};
window.NDCConsentState = estadoReal;
window.dispatchEvent(new CustomEvent('ndc:consent', {detail: estadoReal}));

cmpPermite… son nombres de ejemplo: deben sustituirse por las variables reales de vuestro banner; no pegues el ejemplo sin adaptarlo. Publicidad requiere ad_storage y ad_user_data concedidos. GA4 requiere analytics_storage. Una retirada posterior bloquea envíos pendientes cuando la CMP notifica el cambio. No se aplica retroactivamente a datos ya enviados a Google.

Programar el envío

El módulo encola el pedido sin llamar a Google durante el pago. En la configuración se muestran la dirección del cron y una clave privada. Configura una petición HTTPS POST cada minuto, con la cabecera X-NDC-Cron-Key. Este paso debe hacerlo vuestro técnico o el panel de tareas del alojamiento; el módulo no crea la tarea por sí solo.

curl --fail --silent --show-error --request POST \
  --header "X-NDC-Cron-Key: CLAVE_PRIVADA_DEL_MODULO" \
  "URL_HTTPS_DEL_CRON_MOSTRADA_EN_CONFIGURACION"

El ejemplo contiene marcadores, no credenciales reales. Usa un fichero de configuración privado del servidor para guardar la clave. No publiques la clave en URLs, capturas o fichas de producto. Se procesan hasta 10 pedidos por ejecución y se revisan hasta 100 pedidos pagados recientes sin encolar. Los envíos tienen bloqueo frente a dos cron simultáneos.

Pagos compatibles por estado

Pruebas antes de producción

1. Compra de tarjeta con retorno normal: comprobar pedido, importe, moneda y un solo registro.
2. Compra exprés InstantPay / PayPal: cerrar el navegador después de pagar. Comprobar que la confirmación del proveedor actualiza el pedido y que el cron lo procesa.
3. Probar financiación aprobada y pendiente, transferencia pendiente y cobrada, y contra reembolso cobrado.
4. Repetir la notificación de pago en el entorno de prueba: no debe crear otra compra.
5. Denegar consentimiento: debe quedar bloqueado. Retirarlo antes del cron: no debe salir la compra pendiente.
6. Interrumpir temporalmente la conexión a Google: comprobar reintento con el mismo identificador.
7. Probar devolución y cancelación. Antes del envío se bloquean los estados nativos anulados/reembolsados. Las devoluciones posteriores a un envío no se ajustan automáticamente en esta versión.
8. Revisar la recepción en Google, el diagnóstico y la atribución con pedidos reales autorizados antes de usar los datos para pujar.

Cómo leer el registro

Seguridad, mantenimiento y retirada

Los secretos y las instantáneas se cifran en base de datos con AES-256-GCM usando una clave derivada de la clave de la tienda. No es un gestor externo de secretos: protege también la base de datos y la configuración de PrestaShop. Los tokens no aparecen en el código del navegador. Los registros no incluyen emails en claro.

Las instantáneas finalizadas y los contextos sin actividad se depuran después de 30 días mediante cron. El registro mínimo de pedidos enviados se conserva para evitar duplicados. Al desinstalar no se borran estas tablas ni la configuración. Para una retirada completa, el técnico deberá borrar únicamente las tablas y claves con el prefijo del módulo tras exportar o conservar lo necesario; eliminar ese registro puede causar reenvíos si se reinstala.

Para revertir, desactiva el módulo y su cron y restaura la medición anterior si la habías modificado. No altera importes ni estados de los pedidos. No hace una importación histórica de compras anteriores a su activación.

Documentación oficial

• Measurement Protocol para GA4
• Envío, identificadores y límites temporales
• Validación de eventos
• Confirmación del pago en PrestaShop