Módulo Google Ads para PrestaShop: conversiones por API

Instrucciones de conexión

Qué hace la conexión de Google Ads

Envía pedidos pagados desde PrestaShop a Data Manager API y una acción de conversión web con conversiones multifuente. Google compara el identificador con el recibido por su etiqueta: una compra coincidente no cuenta dos veces dentro de esa misma acción; una compra ausente puede incorporarse e intentar atribuirse con el clic o el email normalizado y hasheado.

Configurar Google Ads y su API

1. En Google Ads → Objetivos → Conversiones, abre la compra web existente. Comprueba que tiene disponible la conexión de una fuente adicional y sigue la configuración de Google. Si no aparece, detén el despliegue del módulo de Ads y comprueba la elegibilidad de la cuenta.
2. Conserva la etiqueta de compra y su identificador de transacción. El módulo no instala la etiqueta web de Google Ads. Si solo tienes la compra importada de GA4, tu técnico deberá preparar una conversión web propia y revisar los objetivos para que ambas no contabilicen la misma venta en las pujas.
3. Anota el ID de la cuenta propietaria de la acción (sin guiones), el ID numérico de la acción y el MCC de acceso si procede. El ID de la acción no es el label alfanumérico de la etiqueta ni el prefijo AW-. En medición entre cuentas puede ser el MCC quien posea la conversión.
4. En tu proyecto de Google Cloud, habilita Data Manager API y configura la pantalla de consentimiento OAuth. Para obtener la autorización con la utilidad incluida, crea un cliente OAuth de tipo aplicación de escritorio y descarga su JSON en tu ordenador.
5. El administrador ejecuta python3 oauth-google.py client_secret.json credenciales-privadas.json en su ordenador. Se abre Google para autorizar la cuenta con acceso a Google Ads. La utilidad solicita https://www.googleapis.com/auth/datamanager y guarda los tres valores necesarios en un fichero local privado.
6. Copia client_id, client_secret y refresh_token en los campos del módulo. Nunca subas los JSON privados a Recursos ni los envíes como parte del ZIP público.
7. Para distribuir una conexión OAuth a usuarios externos desde una aplicación propia de Nivel de Calidad habrá que completar la verificación de Google para el permiso sensible. Esta primera versión usa el proyecto y la autorización de cada instalación; no incluye una aplicación OAuth compartida verificada.
8. Ajusta el valor de conversión al mismo criterio de la etiqueta: productos netos, total sin IVA o total con IVA. Google puede sobrescribir el valor de la etiqueta con el dato enviado desde servidor. Envía euros como 180.00, nunca céntimos como 18000.
9. Prueba primero con validateOnly, después con pedidos nuevos en producción controlada. Google documenta un periodo inicial de prueba de 14 días en multifuente antes de usar las nuevas conversiones para pujar.

La utilidad OAuth se incluye en la descarga adicional «Guía y herramienta OAuth», fuera del ZIP instalable. Descomprime ese paquete en tu ordenador. Renovar credenciales no cambia el destino de los pedidos. Cambiar cuenta, acción, formato del pedido o criterio de importe bloquea las colas anteriores para evitar enviar datos a un destino equivocado.

Datos enviados

ID de pedido, fecha del primer pago confirmado, importe, moneda, consentimiento y GCLID/GBRAID/WBRAID cuando estén disponibles; email del comprador normalizado y convertido en hash SHA-256 si hay consentimiento. Esta versión no envía nombre, dirección, teléfono, IP ni datos de tarjeta. No necesita CRM ni una hoja de cálculo.

El módulo envía pronto mediante cron y detiene reintentos pasados 7 días como límite conservador interno. Google determina finalmente la ventana y elegibilidad de atribución. Sin datos que permitan relacionar el pedido con publicidad no se puede garantizar una conversión de Ads.

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

• Conversiones multifuente: requisitos y deduplicación
• Enviar conversiones web mediante Data Manager API
• Configurar acceso a Data Manager API
• OAuth y puesta en producción