Guía 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 de Composer al repositorio privado del módulo.
• Módulo kowal/base.
• Opcional: Kowal_CookieConsent, si la tienda lo utiliza para GTM y Consent Mode.

Instalación con Composer

composer config repositories.kowal-datalayer vcs composer require kowal/module-datalayerphp bin/magento module:enable Kowal_DataLayerphp bin/magento setup:upgradephp bin/magento cache:flush

En un entorno de producción, si el proyecto lo requiere, ejecute el despliegue estándar de Magento:

php bin/magento setup:di:compilephp bin/magento setup:static-content:deployphp bin/magento cache:flush

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 - active el módulo para el ámbito de configuración seleccionado.
2. Debug Mode - actívelo solo durante las pruebas y la verificación de la implementación.
3. Render Mode - mantenga Server and JavaScript, salvo que haya un motivo para limitar el modo de funcionamiento.
4. Missing Value Strategy - elija si los valores que faltan deben omitirse o enviarse como undefined.
5. Clear Ecommerce Before Push - recomendado Yes.
6. Fail-safe Mode - recomendado Yes; los procesos críticos para las ventas permanecen protegidos incluso si esta opción está desactivada.
7. Log Level - en producción se recomienda Errors only.
8. Log Payloads - actívelo solo de forma temporal.

Product Mapping

1. Product Identifier Attribute - seleccione el atributo utilizado como item_id. Por defecto, sku.
2. Brand Attribute - seleccione el atributo de fabricante/marca. Por defecto, manufacturer.
3. Category Strategy - seleccione la forma de construir item_category.
4. Category Attribute - configúrelo solo cuando la estrategia de categoría utilice un atributo de producto.
5. Configurable Product Strategy - decida si usar los datos del hijo/simple o del padre/configurable.
6. Include Out Of Stock Products On Lists - se aplica a los eventos de listados de productos.

Events

Active 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 del cliente de Magento para los clientes conectados.
2. Send Hashed Email - envía solo el hash SHA-256 del email. El email sin procesar no se envía a dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - actívelo si la tienda utiliza Kowal_CookieConsent.
2. Render GTM From DataLayer Module - deje No si GTM ya se renderiza mediante Cookie Consent u otro módulo.
3. Google Tag Manager ID - configúrelo solo si el renderizado de GTM desde este módulo está activado.
4. purchase_test Redirect Rules - añada solo los métodos de pago que deban utilizar la página intermedia purchase_test.

Modos de reglas de purchase_test:

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

Configuración multistore

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

• idioma;
• moneda;
• feed publicitario;
• atributo identificador del producto;
• atributo de marca;
• estructura de categorías;
• métodos de pago.

Verificación de la implementación

1. Abra Google Tag Manager Preview.
2. Compruebe dataLayer en la consola del navegador o con la extensión DataLayer Checker.
3. Pruebe la página de producto y el evento view_item.
4. Abra una categoría o los resultados de búsqueda y compruebe view_item_list.
5. Haga clic en un producto del listado y compruebe select_item.
6. Añada un producto al carrito y compruebe add_to_cart.
7. Cambie la cantidad o elimine un producto del carrito y compruebe remove_from_cart.
8. Añada un producto a la wishlist y compruebe add_to_wishlist.
9. Entre en el carrito y en el checkout, y compruebe view_cart y begin_checkout.
10. Guarde el método de envío y de pago, y compruebe add_shipping_info y add_payment_info.
11. Realice un pedido de prueba y compruebe purchase.
12. Actualice la página de éxito y asegúrese de que purchase no se duplica.
13. Compruebe var/log/kowal_datalayer.log.

Integración de purchase_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 del 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ía purchase_test y luego redirige al cliente al operador de pago. Si JavaScript o DataLayer no funcionan, la redirección debería seguir ejecutándose.

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

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

Si el método está configurado en modo Adapter Required, el adapter debe implementar:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

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