Kowal Data Layer para Magento 2

Instrucciones de instalación y configuración

Requisitos

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatible con la versión de Magento utilizada.
• Acceso Composer al repositorio privado del módulo.
• El módulokowal/base.
• Permiso para ejecutarsetup:upgrade, ya que el módulo añade campos de atribución a las tablasquoteysales_order.
• Contenedor web de Google Tag Manager, si la tienda va a utilizar las exportaciones de integración ya preparadas.
• Opcionalmente:Kowal_CookieConsent, si la tienda lo utiliza para GTM y Consent Mode.

Instalación con Composer

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, el e-mail del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
composer require kowal/module-datalayer
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flush

El comandosetup:upgradecrea las columnas:

• quote.kowal_attribution_first;
• quote.kowal_attribution_last;
• sales_order.kowal_attribution_first;
• sales_order.kowal_attribution_last.

Las columnas contienen datos serializados de first-touch y last-touch. No deben crearse manualmente.

Actualización de una instalación existente

Antes de actualizar producción, realiza una copia de la base de datos de acuerdo con el procedimiento del proyecto. A continuación, actualiza el paquete y el esquema de Magento:

composer update kowal/module-datalayer --with-dependencies
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flush

En modo producción, vuelve a ejecutar la compilación DI y el deployment de los assets estáticos. Esto es necesario, entre otros motivos, para el nuevo endpoint de atribución, los observadores quote/order y los cambios en el script del frontend.

En el entorno de producción, si el proyecto lo requiere, realiza el deployment estándar de Magento:

php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

Tras actualizar los permisos ACL, es posible que el administrador tenga que volver a iniciar sesión en el panel para ver la posiciónData Layer > GTM Exports.

Configuración básica

Panel de administración:

Stores > Configuration > Kowal > Kowal Data Layer

Menú:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module- activa el módulo para el ámbito de configuración seleccionado.
2. Debug Mode- actívalo solo durante las pruebas y la verificación de la implementación.
3. Render Mode- dejaServer and JavaScriptsi no hay ningún motivo para limitar el modo de funcionamiento.
4. Missing Value Strategy- elige si los valores ausentes deben omitirse o enviarse comoundefined.
5. Clear Ecommerce Before Push- recomendadoYes.
6. Fail-safe Mode- recomendadoYes; los procesos críticos para la venta permanecen protegidos incluso después de desactivar esta opción.
7. Log Level- en producción se recomiendaErrors only.
8. Log Payloads- actívalo solo temporalmente.

Product Mapping

1. Product Identifier Attribute- selecciona el atributo utilizado comoitem_id. Por defecto,sku.
2. Brand Attribute- selecciona el atributo de fabricante/marca. Por defecto,manufacturer.
3. Category Strategy- selecciona la forma de construiritem_category.
4. Category Attribute- configúralo solo si la estrategia de categoría utiliza un atributo de producto.
5. Configurable Product Strategy- decide si se deben usar los datos del hijo/simple o del padre/configurable.
6. Include Out Of Stock Products On Lists- se aplica a los eventos de listas de productos.

Events

Activa los eventos requeridos por la implementación:

• user_data
• view_item_list
• select_item
• view_item
• add_to_cart
• remove_from_cart
• view_cart
• add_to_wishlist
• begin_checkout
• add_shipping_info
• add_payment_info
• purchase
• purchase_test, si la tienda utiliza una página intermedia antes del pago.

Privacy

1. Send User ID- envía el ID de cliente de Magento para los clientes que han iniciado sesión.
2. Send Hashed Email- envía solo el hash SHA-256 del email. El email sin procesar no se envía adataLayer.

Attribution

Capture First and Last Touch Attributionguarda la fuente de entrada del cliente en quote y en el pedido. Ajuste recomendado:Yes.

El ajuste funciona por store view. Tras desactivarlo, el módulo no registra nuevos touchpoints. Los datos guardados anteriormente en pedidos existentes permanecen en la base de datos.

El módulo reconoce:

• parámetrosutm_source,utm_medium,utm_campaign,utm_id,utm_term,utm_contentyutm_source_platform;
• tipos de click ID de Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X y LinkedIn;
• entradas desde resultados de búsqueda orgánicos;
• referrals externos;
• entradas direct.

Se guardanfirst_touchylast_touch, es decir, la última fuente distinta de direct. La navegación habitual entre subpáginas de la tienda no sobrescribe la fuente. Los referrals procedentes de direcciones de pago, callbacks, returns y páginas de éxito se omiten para que el operador de pago no sea reconocido como fuente de la venta.

La captura funciona por dos vías:

• del lado de Magento para entradas estándar no cacheadas;
• mediante una solicitud ligera del navegador para páginas servidas desde FPC o Varnish.

Los datos se mantienen en la sesión de checkout, se guardan en quote y se copian al order antes de realizar el pedido. El mecanismo cubre el frontend clásico, el checkout AJAX/REST y los pedidos creados a partir de un quote que ya contiene atribución.

Los valores sin procesar degclid,fbclidy otros identificadores de clic no se guardan. El módulo conserva únicamente el tipo de parámetro, por ejemplogclid, y la clasificación resultante de la fuente. Los query strings se eliminan de la landing page y del referrer guardados.

La atribución puede comprobarse:

• en la vista del pedido, en la secciónCustomer Attribution;
• endataLayer, en la propiedadattributiondel eventopurchase;
• directamente en las columnaskowal_attribution_firstykowal_attribution_lastde las tablasquoteysales_order.

La captura de la fuente debe incluirse en la documentación de privacidad de la tienda de acuerdo con la política de implementación. El módulo no crea su propio identificador de usuario a largo plazo ni guarda valores de click ID, pero almacena metadatos de campaña y la fuente del pedido.

Integrations

1. Integrate With Kowal Cookie Consent- actívalo si la tienda utilizaKowal_CookieConsent.
2. Render GTM From DataLayer Module- dejaNosi GTM ya se renderiza mediante Cookie Consent u otro módulo.
3. Google Tag Manager ID- configúralo solo cuando la renderización de GTM desde este módulo esté activada.
4. purchase_test Redirect Rules- añade únicamente los métodos de pago que deban usar la página intermediapurchase_test.

Modos de reglaspurchase_test:

• Static URL- úsalo solo para pagos con una dirección fija del operador.
• URL Pattern- úsalo cuando baste un patrón de URL con los placeholders{order_id},{order_increment_id},{store_id}o{quote_id}.
• Adapter Required- úsalo para pasarelas que generan una URL dinámica de transacción. Antes de lanzarlo en producción, hay que añadir un adaptador dedicado para el módulo de pago concreto.

GTM Export Identifiers

En esta sección introduce los identificadores de los servicios que deben incorporarse en los archivos JSON generados:

Los campos pueden estar vacíos si la tienda no utiliza una plataforma determinada. Al guardar la configuración, se verifica el formato de cada valor completado. El botón de exportación comprueba únicamente el conjunto requerido por la plataforma seleccionada, por lo que, por ejemplo, la exportación GA4 no requiere configurar Meta ni TikTok.

Tras completar los campos, haz clic enSave Configy, a continuación, en el botón correspondienteDownload ... JSONdel campoGenerate GTM Exports. El archivo descargado ya contiene los identificadores finales. No es necesario editar las variables constantes después de importarlo a GTM.

Configuración multistore

Configura el módulo a nivel de store view si las tiendas difieren en:

• idioma;
• moneda;
• feed publicitario;
• atributo del identificador de producto;
• atributo de marca;
• estructura de categorías;
• métodos de pago;
• reglas de captura de atribución;
• identificadores de servicios utilizados en los paquetes GTM importados.

Verificación de la implementación

1. Abre Google Tag Manager Preview.
2. CompruebadataLayeren la consola del navegador o con la extensión DataLayer Checker.
3. Prueba la página de producto y el eventoview_item.
4. Abre una categoría o los resultados de búsqueda y compruebaview_item_list.
5. Haz clic en un producto de la lista y compruebaselect_item.
6. Añade un producto al carrito y compruebaadd_to_cart.
7. Cambia la cantidad o elimina un producto del carrito y compruebaremove_from_cart.
8. Añade un producto a la wishlist y compruebaadd_to_wishlist.
9. Entra en el carrito y en el checkout, compruebaview_cartybegin_checkout.
10. Guarda el método de envío y de pago, compruebaadd_shipping_infoyadd_payment_info.
11. Realiza un pedido de prueba y compruebapurchase.
12. Actualiza la página de éxito y asegúrate de quepurchaseno se duplique.
13. Compruebavar/log/kowal_datalayer.log.
14. En una nueva ventana privada, abre la tienda con la URL?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Navega por varias subpáginas, añade un producto al carrito y realiza un pedido.
16. En la vista del pedido, comprueba la secciónCustomer Attributionyattribution.first_touchyattribution.last_touchen el eventopurchase.
17. Confirma quefirst_touch.sourcetiene el valortest,mediumtiene el valorcpcycampaigntiene el valorattribution_test.
18. En la misma ventana y sesión, vuelve a la tienda desde otra fuente etiquetada y confirma quefirst_touchno ha cambiado y quelast_touchse ha actualizado.
19. Si la tienda utiliza una pasarela externa, confirma después de volver del pago que el dominio del operador no ha sustituido la fuente del pedido.

Exportación de la configuración de Google Tag Manager

En el panel de Magento, ve aStores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Hay paquetes independientes disponibles para GA4, Google Ads, Meta, TikTok, Pinterest y Microsoft Ads.

1. Selecciona el ámbito de configuración adecuado:Default Config, website o store view.
2. Completa los identificadores de las plataformas utilizadas y guarda la configuración.
3. Haz clic en el botón de descarga del JSON de la plataforma seleccionada en el campoGenerate GTM Exports.
4. En GTM, crea un nuevo workspace y seleccionaAdmin > Import Container.
5. Indica el archivo descargado y usa el modoMerge.
6. Revisa la lista de variables, reglas y etiquetas que se van a añadir, y confirma que las variables constantes contienen los identificadores correctos.
7. Comprueba los requisitos de consentimiento y ejecuta GTM Preview.
8. Publica el contenedor solo después de confirmar los eventos en la herramienta de diagnóstico de la plataforma.

Los nombres de los elementos llevan el prefijoKowal - nazwa platformy, por lo que los paquetes pueden combinarse en un único contenedor. El eventopurchase_testno se exporta como conversión; las ventas se reportan exclusivamente mediantepurchase.

Si un campo requerido está vacío o tiene un formato incorrecto, el módulo no generará la exportación y mostrará un mensaje indicando el valor que debe corregirse. Esto evita la importación accidental de un contenedor con un placeholder. La página alternativaKowal > Data Layer > GTM Exportssigue estando disponible, pero utiliza valores del ámbitoDefault Config; para implementaciones multistore se recomiendan los botones de la configuración.

Las exportaciones corresponden al contenedor web y al envío browser-side. No sustituyen a las integraciones server-side, como Meta Conversions API o TikTok Events API.

Consentimientos y publicación de GTM

• Las etiquetas publicitarias requierenad_storage,ad_user_datayad_personalization.
• GA4 utiliza los mecanismos de consentimiento integrados de Google tag.
• Si GTM renderizaKowal_CookieConsent, dejaRender GTM From DataLayer Moduleconfigurados comoNo.
• No publiques el contenedor sin comprobar Consent Mode, GTM Preview y el diagnóstico de eventos de la plataforma correspondiente.
• Con un CSP restrictivo, añade los dominios de scripts y endpoints de las plataformas seleccionadas de acuerdo con su documentación.

Integraciónpurchase_test

Si el método de pago redirige al cliente fuera de la tienda y conoce la URL de destino del operador, la integración de pago puede usar:

Kowal\DataLayer\Model\PurchaseTestRedirect::prepare($paymentRedirectUrl)

El método devuelve la URL de la página intermedia del módulo. La página intermedia envíapurchase_testy, a continuación, redirige al cliente al operador de pago. Si JavaScript o DataLayer no funciona, la redirección debería ejecutarse igualmente.

Para una integración en la que la URL depende del pedido o del token de transacción, usa:

Kowal\DataLayer\Model\PurchaseTestRedirect::prepareForOrder($order, $fallbackRedirectUrl)

Si el método está configurado en modoAdapter Required, el adaptador debe implementar:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

El adaptador debe registrarse en DI como elemento del arrayadaptersparaKowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. El adaptador es el lugar adecuado para la lógica dependiente de un operador de pago concreto.

Diagnóstico

Falta la sección Customer Attribution en el pedido

1. Comprueba siCapture First and Last Touch Attributionestá activado para la store view correcta.
2. Confirma la ejecución dephp bin/magento setup:upgradey la presencia de las cuatro columnas de atribución.
3. Limpia la cache de configuración y de layout.
4. Realiza una prueba en una nueva ventana privada con una URL marcada con UTM.
5. Compruebavar/log/kowal_datalayer.logen busca de mensajesattribution capture failedoattribution assignment failed.

La atribución funciona sin FPC, pero no funciona con Varnish

1. Comprueba en las herramientas de desarrollador la solicitud POST akowal_datalayer/attribution/capture.
2. Confirma que la solicitud tiene estado200y se ejecuta en el mismo dominio de la tienda.
3. Comprueba si CSP, WAF o las reglas de reverse proxy no bloquean el endpoint.
4. Después del deployment, asegúrate de que se ha publicado el archivo actualview/frontend/web/js/data-layer.js.

La compra tiene una fuente incorrecta del operador de pago

Comprueba si el pedido se creó a partir de un quote que contenía atribución antes de la redirección. Las rutas que contienenpayment,callback,returnosuccessno deberían sobrescribir last-touch con el referral. Si un módulo de pago personalizado utiliza otra secuencia, verifica el momento de creación del order y del guardado del quote.

La importación de GTM informa de conflictos

Usa el modoMergey revisa los detalles de los cambios. Los elementos de las exportaciones tienen el prefijoKowal - ...; si en el contenedor existen elementos modificados con el mismo nombre, elige de forma consciente si sobrescribirlos o cambiarles el nombre. Después de cambiar los nombres, comprueba las referencias de las etiquetas a variables y triggers.