Kowal Data Layer para Magento 2
- Compatibilidade
- 2.4.9, 2.4.8, 2.4.7, 2.4.6, 2.4.5, 2.4.4, 2.4.3, 2.4.2, 2.4.1, 2.4.0
- Hyva Theme
- Hyva Theme Redy
Descrição / Kowal Data Layer para Magento 2
MAGENTO 2 · ECOMMERCE · GTM · ATRIBUIÇÃO
Associe os eventos ecommerce à origem da encomenda.
Kowal Data Layer
Prepare os dados de compra do Magento para GA4 e para a configuração de tags publicitárias. Guarde o first touch e o last non-direct touch na encomenda e verifique a implementação das tags na pré-visualização do GTM.
Eventos ecommerce · Exportações GTM · Atribuição no painel
COMO FUNCIONA NA PRÁTICA
01 · Escolhe dados e identificadores
Define item_id, marca, categoria e Store View.
02 · Configura tags e consentimento
Importa a exportação GTM e liga-a ao CMP.
03 · Verifica eventos e encomendas
Confirma valores, moedas e a atribuição guardada.
O que ganha a sua loja?
Conheça as funcionalidades, a utilização e as definições do módulo.
Data Layer Magento 2 para GA4, GTM e atribuição de vendas
Kowal Data Layer cria uma camada de dados ecommerce coerente diretamente a partir do Magento 2. Suporta todo o percurso de compra, integrações via Google Tag Manager e o registo da origem de uma encomenda específica.
É uma solução para lojas que querem ligar a analítica GA4, campanhas publicitárias e dados Magento sem adicionar manualmente scripts a elementos sucessivos do tema e do checkout.
GA4 ecommerce
Eventos desde a lista de produtos e PDP, passando pelo carrinho, wishlist e checkout, até à compra.
Exportações GTM prontas a usar
Pacotes para GA4, Google Ads, Meta, TikTok, Pinterest, Microsoft Ads e OpenAI Ads.
Atribuição de encomendas
First touch e last non-direct touch com informação sobre origem, meio, campanha, landing page e referrer.
A analítica não pode bloquear as vendas
O módulo foi concebido num modelo fail-safe. Os erros da camada de dados ou de atribuição são isolados e registados, mas não devem interromper o carrinho, o checkout, a encomenda nem o redirecionamento para pagamento.
Eventos ecommerce suportados
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 e purchase_test.
Multistore e feeds de produto
A configuração por Store View permite ajustar identificadores, moeda, nomes, categoria e marca. item_id pode corresponder aos identificadores utilizados no Google Merchant Center, Meta Catalog e outros feeds.
Consent Mode
O módulo pode funcionar com Kowal Cookie Consent. O Data Layer é responsável pelos dados ecommerce e o CMP pelo consentimento e pela ativação das tags adequadas.
FAQ
O módulo substitui o Google Tag Manager?
Não. Prepara dados ecommerce e exportações de configuração prontas, que podem ser utilizadas no GTM.
Funciona com Varnish e FPC?
Sim, a solução contempla lojas que utilizam cache e elementos dinâmicos do checkout.
Guarda a origem da encomenda no Magento?
Sim. A atribuição first touch e last non-direct touch é copiada do carrinho para a encomenda.
Suporta lojas multistore?
Sim. A configuração de identificadores e dados pode funcionar ao nível do Store View.
Um erro de analítica pode bloquear o checkout?
A arquitetura foi concebida para que os erros analíticos fiquem isolados do processo de venda.
A exportação GTM é o início da implementação
Kowal → Data Layer → GTM Exports permite descarregar um JSON para a plataforma selecionada após a configuração dos identificadores. Importe o pacote para o workspace GTM através de Merge, verifique as tags e o Preview e só depois publique a configuração.
A atualização do módulo Magento não atualiza tags GTM anteriormente importadas. Descarregue novamente a exportação adequada quando a respetiva lógica mudar e verifique duplicações de tags e conversões.
Atribuição no painel e limites da medição
Data Layer → Customer Attribution mostra encomendas com atribuição guardada, incluindo compras de convidados. A grelha tem filtros, ordenação e vistas guardadas; o acesso exige uma permissão de função separada.
Fontes UTM, tipos de click ID, organic e referral são reconhecidos sem guardar queries completas nem click ID publicitários em bruto. Os dados refletem entradas reconhecidas, não uma visão completa de todos os contactos do cliente em diferentes dispositivos.
Purchase e o purchase_test de diagnóstico
purchase_test no checkout REST padrão significa a criação da encomenda, não o pagamento da compra. As tags de conversão exportadas ignoram-no. O evento exige ativação separada na configuração.
Os redirecionamentos para gateways de pagamento personalizados podem exigir um adaptador. Nos logs var/log/kowal_datalayer.log pode verificar erros; o projeto isola-os do processo de venda.
Consentimento, dados privados e cache
O CMP gere consentimentos e a atualização do respetivo estado. Quando Kowal Cookie Consent carrega o GTM, desative o segundo loader GTM no Data Layer. A exportação de tags por si só não substitui a configuração de consentimentos.
A identidade do utilizador é obtida a partir de um endpoint privado para não misturar dados de clientes no FPC. Para um loader GTM externo, considere a disponibilidade de user_data, os consentimentos corretos e o resultado no Preview.
Hyvä e conformidade dos identificadores
O pacote inclui o Kowal_DataLayerHyva opcional, ativado em conjunto com Enable Hyva Integration para o Store View adequado. O adaptador suporta private-content, listas dinâmicas e FormData.
O checkout REST padrão está incluído no âmbito. Hyvä Checkout/Magewire e GraphQL exigem integração separada. item_id na exportação deve corresponder aos identificadores do feed ou catálogo publicitário correto.
Instalação via Composer
Pacote kowal/module-datalayer, módulo Kowal_DataLayer. Depois de configurar o acesso ao repositório Kowal, instale o pacote, ative o módulo, atualize o Magento e limpe a cache. Em produção, considere a compilação e a implementação de conteúdo estático de acordo com o processo da loja.
Da configuração ao resultado
1. Escolhe dados e identificadores
Define item_id, marca, categoria e Store View.
2. Configura tags e consentimento
Importa a exportação GTM e liga-a ao CMP.
3. Verifica eventos e encomendas
Confirma valores, moedas e a atribuição guardada.
Da entrada pela campanha à encomenda
O cliente chega a partir de uma campanha, vê um produto e conclui a compra. O módulo guarda as origens reconhecidas no quote e transfere-as para a encomenda.
No painel, compara first touch e last non-direct touch. No GTM Preview, verifica o evento purchase com valor, moeda e itens.
Organize os dados ecommerce e a atribuição de vendas
Quer adaptar o módulo à sua loja? Peça a implementação do Kowal Data Layer e discuta a configuração ou as extensões necessárias.
Mais informação
| Hyva Theme | Hyva Theme Redy |
|---|---|
| Compatibilidade com o modelo | Hyvä, Luma / Blank, KOWAL |
Manual de instalação do módulo
Instruções de instalação e configuração
Requisitos
- Magento Open Source / Adobe Commerce 2.4.x.
- PHP compatível com a versão Magento utilizada.
- Acesso Composer ao repositório privado do módulo.
- Módulo
kowal/base. - Permissão para executar
setup:upgrade, porque o módulo adiciona campos de atribuição às tabelasquoteesales_order. - Contentor web do Google Tag Manager, se a loja tiver de utilizar exportações de integração prontas.
- Opcionalmente:
Kowal_CookieConsent, se a loja o utilizar para GTM e Consent Mode.
Instalação com Composer
Receberá por e-mail os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, após a compra. Também estão disponíveis no painel do cliente depois de iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do 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:flushO comando setup:upgrade cria as colunas:
quote.kowal_attribution_first;quote.kowal_attribution_last;sales_order.kowal_attribution_first;sales_order.kowal_attribution_last.
As colunas contêm dados serializados de first-touch e last-touch. Não devem ser criadas manualmente.
Atualização de uma instalação existente
Antes de atualizar a produção, faça uma cópia da base de dados de acordo com o procedimento do projeto. Em seguida, atualize o pacote e o esquema Magento:
composer update kowal/module-datalayer --with-dependencies
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flushNo modo de produção, execute novamente a compilação DI e o deployment dos assets estáticos. Isto é necessário, entre outros, para o novo endpoint de atribuição, os observadores quote/order e as alterações no script frontend.
No ambiente de produção, se o projeto assim o exigir, execute o deployment Magento padrão:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flushDepois da atualização das permissões ACL, o administrador pode ter de voltar a iniciar sessão no painel para ver a posição Data Layer > GTM Exports.
Configuração básica
Painel administrativo:
Stores > Configuration > Kowal > Kowal Data Layer
Menu:
kowal.store > Modules > Data Layer > Settings
General
Enable Module- ative o módulo para o âmbito de configuração selecionado.Debug Mode- ative apenas durante testes e verificação da implementação.Render Mode- mantenhaServer and JavaScript, se não houver motivo para limitar o modo de funcionamento.Missing Value Strategy- escolha se os valores em falta devem ser omitidos ou enviados comoundefined.Clear Ecommerce Before Push- recomendadoYes.Fail-safe Mode- recomendadoYes; os processos críticos para as vendas continuam protegidos mesmo após a desativação desta opção.Log Level- em produção, recomendadoErrors only.Log Payloads- ative apenas temporariamente.
Product Mapping
Product Identifier Attribute- escolha o atributo utilizado comoitem_id. Por predefiniçãosku.Brand Attribute- escolha o atributo do fabricante/marca. Por predefiniçãomanufacturer.Category Strategy- escolha a forma de construiritem_category.Category Attribute- defina apenas quando a estratégia de categoria utiliza o atributo do produto.Configurable Product Strategy- decida se pretende utilizar dados do filho/simple ou do pai/configurable.Include Out Of Stock Products On Lists- aplica-se aos eventos de listas de produtos.
Events
Ative os eventos exigidos pela implementação:
user_dataview_item_listselect_itemview_itemadd_to_cartremove_from_cartview_cartadd_to_wishlistbegin_checkoutadd_shipping_infoadd_payment_infopurchasepurchase_test, se a loja utilizar uma página intermédia antes do pagamento.
Privacy
Send User ID- envia o ID do cliente Magento para clientes autenticados.Send Hashed Email- envia apenas o hash SHA-256 do e-mail. O e-mail em bruto não é enviado paradataLayer.
Attribution
Capture First and Last Touch Attribution guarda a origem da entrada do cliente no quote e na encomenda. Definição recomendada: Yes.
A definição funciona por store view. Depois de desativada, o módulo não regista novos touchpoints. Os dados anteriormente guardados em encomendas existentes permanecem na base.
O módulo reconhece:
- parâmetros
utm_source,utm_medium,utm_campaign,utm_id,utm_term,utm_contenteutm_source_platform; - tipos de click ID Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X e LinkedIn;
- entradas a partir de resultados orgânicos de pesquisa;
- referrals externos;
- entradas direct.
São guardados first_touch e last_touch, ou seja, a última origem que não é direct. A navegação normal entre subpáginas da loja não substitui a origem. Referrals de endereços de pagamento, callbacks, returns e páginas de sucesso são ignorados para que o operador de pagamento não seja considerado a origem da venda.
A captura funciona em dois modos:
- do lado do Magento para entradas padrão não cacheadas;
- através de um pedido leve do navegador para páginas servidas a partir de FPC ou Varnish.
Os dados são mantidos na sessão de checkout, guardados no quote e copiados para order antes da submissão da encomenda. O mecanismo abrange o frontend clássico, checkout AJAX/REST e encomendas criadas a partir de quote que já contém atribuição.
Os valores em bruto de gclid, fbclid e dos restantes identificadores de clique não são guardados. O módulo conserva apenas o tipo de parâmetro, por exemplo gclid, e a classificação de origem resultante. As query strings são removidas da landing page e do referrer guardados.
A atribuição pode ser verificada:
- na vista da encomenda, na secção
Customer Attribution; - em
dataLayer, na propriedadeattributiondo eventopurchase; - diretamente nas colunas
kowal_attribution_firstekowal_attribution_lastdas tabelasquoteesales_order.
A captura da origem deve ser incluída na documentação de privacidade da loja, de acordo com a política de implementação. O módulo não cria o seu próprio identificador de utilizador de longo prazo e não guarda valores click ID, mas armazena metadados da campanha e a origem da encomenda.
Integrations
Integrate With Kowal Cookie Consent- ative se a loja utilizarKowal_CookieConsent.Render GTM From DataLayer Module- deixeNose o GTM já for renderizado pelo Cookie Consent ou por outro módulo.Google Tag Manager ID- defina apenas quando a renderização do GTM a partir deste módulo estiver ativada.purchase_test Redirect Rules- adicione apenas os métodos de pagamento que devem utilizar a página intermédiapurchase_test.
Modos de 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 de lançar em produção, é necessário adicionar um adaptador dedicado para o módulo de pagamento específico.
GTM Export Identifiers
Nesta secção, introduza os identificadores dos serviços que devem ser incorporados nos ficheiros JSON gerados:
| Campo no Magento | Valor |
|---|---|
GA4 Measurement ID | identificador no formato G-XXXXXXXXXX |
Google Ads Conversion ID | identificador no formato AW-XXXXXXXXX |
Google Ads Purchase Conversion Label | etiqueta da ação de conversão de compra |
Meta Pixel ID | Pixel ID numérico |
TikTok Pixel ID | Pixel ID alfanumérico |
Pinterest Tag ID | Tag ID numérico |
Microsoft Ads UET Tag ID | UET Tag ID numérico |
Os campos podem ficar vazios se a loja não utilizar uma determinada plataforma. Ao guardar a configuração, é verificado o formato de cada valor preenchido. O botão de exportação verifica apenas o conjunto exigido pela plataforma selecionada, por isso, por exemplo, a exportação GA4 não exige a configuração de Meta nem TikTok.
Depois de preencher os campos, clique em Save Config e, em seguida, no botão Download ... JSON adequado no campo Generate GTM Exports. O ficheiro descarregado já contém os identificadores finais. Não é necessário editar variáveis constantes após a importação para o GTM.
Configuração multistore
Configure o módulo ao nível do store view se as lojas diferirem em:
- idioma;
- moeda;
- feed publicitário;
- atributo de identificador do produto;
- atributo de marca;
- estrutura de categorias;
- métodos de pagamento;
- regras de captura de atribuição;
- identificadores de serviços utilizados nos pacotes GTM importados.
Verificação da implementação
- Abra o Google Tag Manager Preview.
- Verifique
dataLayerna consola do navegador ou com a extensão DataLayer Checker. - Teste a página de produto e o evento
view_item. - Abra uma categoria ou resultados de pesquisa e verifique
view_item_list. - Clique num produto na lista e verifique
select_item. - Adicione o produto ao carrinho e verifique
add_to_cart. - Altere a quantidade ou remova o produto do carrinho e verifique
remove_from_cart. - Adicione o produto à wishlist e verifique
add_to_wishlist. - Entre no carrinho e no checkout, verifique
view_cartebegin_checkout. - Guarde o método de entrega e de pagamento, verifique
add_shipping_infoeadd_payment_info. - Faça uma encomenda de teste e verifique
purchase. - Atualize a página de sucesso e confirme que
purchasenão é duplicado. - Verifique
var/log/kowal_datalayer.log. - Numa nova janela privada, abra a loja com o URL
?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test. - Navegue por algumas subpáginas, adicione um produto ao carrinho e faça uma encomenda.
- Na vista da encomenda, verifique a secção
Customer Attributioneattribution.first_toucheattribution.last_touchno eventopurchase. - Confirme que
first_touch.sourcetem o valortest,mediumtem o valorcpcecampaigntem o valorattribution_test. - Na mesma janela e sessão, regresse à loja a partir de outra origem marcada e confirme que
first_touchpermaneceu sem alterações elast_touchfoi atualizado. - Se a loja utilizar um gateway externo, confirme após o regresso do pagamento que o domínio do operador não substituiu a origem da encomenda.
Exportação da configuração do Google Tag Manager
No painel Magento, aceda a Stores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Estão disponíveis pacotes separados para GA4, Google Ads, Meta, TikTok, Pinterest e Microsoft Ads.
- Escolha o âmbito de configuração correto:
Default Config, website ou store view. - Preencha os identificadores das plataformas utilizadas e guarde a configuração.
- Clique no botão de descarregamento JSON da plataforma selecionada no campo
Generate GTM Exports. - No GTM, crie um novo workspace e escolha
Admin > Import Container. - Indique o ficheiro descarregado e utilize o modo
Merge. - Reveja a lista de variáveis, regras e tags adicionadas e confirme que as variáveis constantes contêm os identificadores corretos.
- Verifique os requisitos de consentimento e execute o GTM Preview.
- Publique o contentor apenas após confirmar os eventos na ferramenta de diagnóstico da plataforma.
Os nomes dos elementos são precedidos pelo prefixo Kowal - nazwa platformy, pelo que os pacotes podem ser combinados num único contentor. O evento purchase_test não é exportado como conversão; as vendas são reportadas exclusivamente por purchase.
Se um campo obrigatório estiver vazio ou tiver um formato inválido, o módulo não gerará a exportação e apresentará uma mensagem com a indicação do valor a corrigir. Isto evita a importação acidental de um contentor com placeholder. A página alternativa Kowal > Data Layer > GTM Exports permanece disponível, mas utiliza valores do âmbito Default Config; para implementações multistore, são recomendados os botões na configuração.
As exportações dizem respeito ao contentor web e ao envio browser-side. Não substituem integrações server-side, como Meta Conversions API ou TikTok Events API.
Consentimentos e publicação GTM
- As tags publicitárias exigem
ad_storage,ad_user_dataead_personalization. - GA4 utiliza os mecanismos de consentimento incorporados da Google tag.
- Se o GTM for renderizado por
Kowal_CookieConsent, mantenhaRender GTM From DataLayer Moduledefinido comoNo. - Não publique o contentor sem verificar o Consent Mode, o GTM Preview e a diagnostica de eventos da plataforma adequada.
- Com CSP restritivo, adicione os domínios de scripts e endpoints das plataformas selecionadas de acordo com a respetiva documentação.
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 depois redireciona o cliente para o operador de pagamento. Se JavaScript ou DataLayer não funcionar, o redirecionamento ainda deve 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 adaptador deve implementar:
Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterfaceO adaptador deve ser registado em DI como elemento da matriz adapters para Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. O adaptador é o local adequado para a lógica dependente do operador de pagamento específico.
Diagnóstico
Secção Customer Attribution em falta na encomenda
- Verifique se
Capture First and Last Touch Attributionestá ativado para o store view correto. - Confirme a execução de
php bin/magento setup:upgradee a presença das quatro colunas de atribuição. - Limpe a cache de configuração e layout.
- Execute o teste numa nova janela privada com um URL UTM marcado.
- Verifique
var/log/kowal_datalayer.logquanto a mensagensattribution capture failedouattribution assignment failed.
A atribuição funciona sem FPC, mas não funciona com Varnish
- Verifique nas ferramentas de programador o pedido POST para
kowal_datalayer/attribution/capture. - Confirme que o pedido tem o estado
200e é executado para o mesmo domínio da loja. - Verifique se CSP, WAF ou regras de reverse proxy não bloqueiam o endpoint.
- Após o deployment, certifique-se de que o ficheiro atual
view/frontend/web/js/data-layer.jsfoi publicado.
A compra tem uma origem incorreta do operador de pagamento
Verifique se a encomenda foi criada a partir de um quote que continha atribuição antes do redirecionamento. As rotas que contêm payment, callback, return ou success não devem substituir last-touch pelo referral. Se um módulo de pagamento personalizado utilizar uma sequência diferente, verifique o momento de criação de order e de gravação do quote.
A importação GTM comunica conflitos
Utilize o modo Merge e reveja os detalhes das alterações. Os elementos das exportações têm o prefixo Kowal - ...; se no contentor existirem elementos modificados com o mesmo nome, escolha conscientemente substituir ou mudar o nome. Depois de alterar nomes, verifique as referências das tags às variáveis e triggers.