Instruções de instalação e configuração

Requisitos

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatível com a versão de Magento utilizada.
• Acesso Composer ao repositório privado do módulo.
• Módulo kowal/base.
• Opcionalmente: Kowal_CookieConsent, se a loja o utilizar para GTM e Consent Mode.

Instalação com 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

Em ambiente de produção, se o projeto o exigir, execute o deployment padrão do Magento:

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

Configuração básica

Painel de administração:

Stores > Configuration > Kowal > Kowal Data Layer

Menu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - ative o módulo para o âmbito de configuração selecionado.
2. Debug Mode - ative apenas durante testes e verificação da implementação.
3. Render Mode - mantenha Server and JavaScript, se não houver motivo para limitar o modo de funcionamento.
4. Missing Value Strategy - escolha se os valores em falta devem ser ignorados ou enviados como undefined.
5. Clear Ecommerce Before Push - recomendado Yes.
6. Fail-safe Mode - recomendado Yes; os processos críticos para as vendas permanecem protegidos mesmo após desativar esta opção.
7. Log Level - em produção, recomendado Errors only.
8. Log Payloads - ative apenas temporariamente.

Product Mapping

1. Product Identifier Attribute - escolha o atributo utilizado como item_id. Por predefinição, sku.
2. Brand Attribute - escolha o atributo do fabricante/marca. Por predefinição, manufacturer.
3. Category Strategy - escolha a forma de construir item_category.
4. Category Attribute - defina apenas se a estratégia de categoria utilizar um atributo de produto.
5. Configurable Product Strategy - decida se deve utilizar dados do filho/simple ou do pai/configurable.
6. Include Out Of Stock Products On Lists - aplica-se aos eventos de listas de produtos.

Events

Ative os eventos exigidos pela implementação:

• 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, se a loja utilizar a página intermédia antes do pagamento.

Privacy

1. Send User ID - envia o ID do cliente Magento para clientes autenticados.
2. Send Hashed Email - envia apenas o hash SHA-256 do email. O email em bruto não é enviado para o dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - ative se a loja utilizar Kowal_CookieConsent.
2. Render GTM From DataLayer Module - mantenha No se o GTM já for renderizado pelo Cookie Consent ou por outro módulo.
3. Google Tag Manager ID - defina apenas se a renderização do GTM a partir deste módulo estiver ativada.
4. purchase_test Redirect Rules - adicione apenas os métodos de pagamento que devem utilizar a página intermédia purchase_test.

Modos das regras purchase_test:

• Static URL - utilize apenas para pagamentos com endereço fixo do operador.
• URL Pattern - utilize quando for suficiente um padrão de URL com placeholders {order_id}, {order_increment_id}, {store_id} ou {quote_id}.
• Adapter Required - utilize para gateways que geram um URL de transação dinâmico. Antes da ativação em produção, é necessário adicionar um adapter dedicado para o módulo de pagamento específico.

Configuração multistore

Configure o módulo ao nível de store view se as lojas diferirem em:

• idioma;
• moeda;
• feed publicitário;
• atributo do identificador do produto;
• atributo da marca;
• estrutura de categorias;
• métodos de pagamento.

Verificação da implementação

1. Abra o Google Tag Manager Preview.
2. Verifique o dataLayer na consola do navegador ou com a extensão DataLayer Checker.
3. Teste a página de produto e o evento view_item.
4. Abra uma categoria ou os resultados de pesquisa e verifique view_item_list.
5. Clique num produto da lista e verifique select_item.
6. Adicione um produto ao carrinho e verifique add_to_cart.
7. Altere a quantidade ou remova um produto do carrinho e verifique remove_from_cart.
8. Adicione um produto à wishlist e verifique add_to_wishlist.
9. Entre no carrinho e no checkout, verifique view_cart e begin_checkout.
10. Guarde o método de envio e de pagamento, verifique add_shipping_info e add_payment_info.
11. Faça uma encomenda de teste e verifique purchase.
12. Atualize a página de sucesso e certifique-se de que purchase não se duplica.
13. Verifique var/log/kowal_datalayer.log.

Integração purchase_test

Se o método de pagamento redirecionar o cliente para fora da loja e conhecer o URL de destino do operador, a integração de pagamento pode utilizar:

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

O método devolve o URL da página intermédia do módulo. A página intermédia envia purchase_test e, em seguida, redireciona o cliente para o operador de pagamento. Se o JavaScript ou o DataLayer não funcionar, o redirecionamento deverá ainda assim ser executado.

Para uma integração em que o URL depende da encomenda ou do token da transação, utilize:

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

Se o método estiver definido no modo Adapter Required, o adapter deverá implementar:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

O adapter deve ser registado em DI como elemento do array adapters para Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. O adapter é o local adequado para a lógica dependente de um operador de pagamento específico.