Kowal Data Layer para Magento 2

Kowal Data Layer é um módulo Magento 2 para implementar GA4 ecommerce através do Google Tag Manager.
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
30,75 €
Enviar por Email a um Amigo

Pedir informações sobre este produto

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 tabelas quote e sales_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:flush

O 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:flush

No 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:flush

Depois 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

  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 omitidos ou enviados como undefined.
  5. Clear Ecommerce Before Push - recomendado Yes.
  6. Fail-safe Mode - recomendado Yes; os processos críticos para as vendas continuam protegidos mesmo após a desativação desta 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 quando a estratégia de categoria utiliza o atributo do produto.
  5. Configurable Product Strategy - decida se pretende 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 uma 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 e-mail. O e-mail em bruto não é enviado para dataLayer.

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_content e utm_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 propriedade attribution do evento purchase;
  • diretamente nas colunas kowal_attribution_first e kowal_attribution_last das tabelas quote e sales_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

  1. Integrate With Kowal Cookie Consent - ative se a loja utilizar Kowal_CookieConsent.
  2. Render GTM From DataLayer Module - deixe No se o GTM já for renderizado pelo Cookie Consent ou por outro módulo.
  3. Google Tag Manager ID - defina apenas quando 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 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 MagentoValor
GA4 Measurement IDidentificador no formato G-XXXXXXXXXX
Google Ads Conversion IDidentificador no formato AW-XXXXXXXXX
Google Ads Purchase Conversion Labeletiqueta da ação de conversão de compra
Meta Pixel IDPixel ID numérico
TikTok Pixel IDPixel ID alfanumérico
Pinterest Tag IDTag ID numérico
Microsoft Ads UET Tag IDUET 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

  1. Abra o Google Tag Manager Preview.
  2. Verifique 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 resultados de pesquisa e verifique view_item_list.
  5. Clique num produto na lista e verifique select_item.
  6. Adicione o produto ao carrinho e verifique add_to_cart.
  7. Altere a quantidade ou remova o produto do carrinho e verifique remove_from_cart.
  8. Adicione o 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 entrega 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 confirme que purchase não é duplicado.
  13. Verifique var/log/kowal_datalayer.log.
  14. Numa nova janela privada, abra a loja com o URL ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
  15. Navegue por algumas subpáginas, adicione um produto ao carrinho e faça uma encomenda.
  16. Na vista da encomenda, verifique a secção Customer Attribution e attribution.first_touch e attribution.last_touch no evento purchase.
  17. Confirme que first_touch.source tem o valor test, medium tem o valor cpc e campaign tem o valor attribution_test.
  18. Na mesma janela e sessão, regresse à loja a partir de outra origem marcada e confirme que first_touch permaneceu sem alterações e last_touch foi atualizado.
  19. 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.

  1. Escolha o âmbito de configuração correto: Default Config, website ou store view.
  2. Preencha os identificadores das plataformas utilizadas e guarde a configuração.
  3. Clique no botão de descarregamento JSON da plataforma selecionada no campo Generate GTM Exports.
  4. No GTM, crie um novo workspace e escolha Admin > Import Container.
  5. Indique o ficheiro descarregado e utilize o modo Merge.
  6. Reveja a lista de variáveis, regras e tags adicionadas e confirme que as variáveis constantes contêm os identificadores corretos.
  7. Verifique os requisitos de consentimento e execute o GTM Preview.
  8. 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_data e ad_personalization.
  • GA4 utiliza os mecanismos de consentimento incorporados da Google tag.
  • Se o GTM for renderizado por Kowal_CookieConsent, mantenha Render GTM From DataLayer Module definido como No.
  • 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\PurchaseTestRedirectAdapterInterface

O 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

  1. Verifique se Capture First and Last Touch Attribution está ativado para o store view correto.
  2. Confirme a execução de php bin/magento setup:upgrade e a presença das quatro colunas de atribuição.
  3. Limpe a cache de configuração e layout.
  4. Execute o teste numa nova janela privada com um URL UTM marcado.
  5. Verifique var/log/kowal_datalayer.log quanto a mensagens attribution capture failed ou attribution assignment failed.

A atribuição funciona sem FPC, mas não funciona com Varnish

  1. Verifique nas ferramentas de programador o pedido POST para kowal_datalayer/attribution/capture.
  2. Confirme que o pedido tem o estado 200 e é executado para o mesmo domínio da loja.
  3. Verifique se CSP, WAF ou regras de reverse proxy não bloqueiam o endpoint.
  4. Após o deployment, certifique-se de que o ficheiro atual view/frontend/web/js/data-layer.js foi 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.

Pressione para saltar o carrossel

Encontrámos outros produtos que podem ser do seu interesse!

Escreva a sua própria avaliação
Está a avaliar: Kowal Data Layer para Magento 2
A sua classificação:
Preço
Qualidade
Suporte
loader
Carregando...

Classificação enviada para aprovação.

Perguntas e respostas

Question
Czy Kowal Data Layer zastępuje Google Tag Manager?
Answer
Nie. Moduł przygotowuje spójną warstwę danych ecommerce oraz konfigurację, którą można wykorzystać w Google Tag Manager. GTM pozostaje narzędziem do uruchamiania i zarządzania tagami.
Question
Jakie zdarzenia GA4 ecommerce obsługuje moduł?
Answer
Moduł obsługuje kluczowe zdarzenia ścieżki zakupowej, m.in. 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 i purchase.
Question
Czy moduł zapisuje źródło konkretnego zamówienia?
Answer
Tak. Obsługuje atrybucję first touch oraz last non-direct touch i może zapisywać przy zamówieniu m.in. źródło, medium, kampanię, landing page i referrer.
Question
Czy Kowal Data Layer działa w sklepach multistore?
Answer
Tak. Konfiguracja może działać na poziomie Store View, co pozwala dopasować identyfikatory i dane do różnych wersji sklepu.
Question
Czy moduł współpracuje z Consent Mode i CMP?
Answer
Tak. Data Layer odpowiada za dane ecommerce, natomiast zarządzanie zgodami może być realizowane przez CMP, np. Kowal Cookie Consent.
Question
Czy błąd analityki może zablokować checkout?
Answer
Moduł został zaprojektowany w modelu fail-safe: błędy warstwy danych lub atrybucji są izolowane i logowane, aby nie zatrzymywać koszyka, checkoutu ani procesu składania zamówienia.
Alterar preferências de cookies