DfGtagManager: documentação completa

O DfGtagManager é uma extensão Shopware 6.7 que injeta um contentor Google Tag Manager, emite os eventos GA4 de comércio eletrónico completos, gere o Consent Mode v2 com o banner de cookies nativo do Shopware, envia as Enhanced Conversions em hash SHA-256, e alinha o data layer com o seu feed do Google Merchant Center. Esta documentação cobre a instalação, a configuração completa e a verificação.

Pré-requisitos

• Shopware 6.7.0 ou mais recente
• PHP 8.2 no mínimo
• Acesso SSH ou à administração do Shopware para instalar o ZIP
• Uma conta Google Tag Manager (recomendado) ou, no mínimo, uma conta Google Analytics 4
• Para as Enhanced Conversions: uma conta Google Ads com campanhas de conversão configuradas

Instalação

Três métodos possíveis consoante o seu ambiente.

A partir da administração do Shopware

1. No back-office: Extensões → As minhas extensões → Carregar a extensão
2. Selecione o ficheiro DfGtagManager.zip
3. Clique em Instalar e depois em Ativar
4. Limpe a cache: Definições → Sistema → Cache e índice → Limpar e regenerar

A partir da linha de comandos (recomendado em produção)

cd /caminho/para/shopware
unzip DfGtagManager.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:install --activate DfGtagManager
bin/console assets:install
bin/console cache:clear

Configuração

Abra a configuração: Extensões → As minhas extensões → DataFirefly Google Tag Manager → menu ⋮ → Configurar. Selecione o sales channel em causa no topo do ecrã: cada sales channel pode ter a sua própria configuração independente.

Definições gerais

• Ativar a extensão: interruptor principal. Desative para cortar toda a injeção sem desinstalar.
• Modo de depuração: mostra registos com o prefixo [DfGtag] na consola do navegador (add_to_cart, remove_from_cart, consent update e outros). A ativar apenas em ambiente de teste.

Google Tag Manager

• GTM Container ID: formato GTM-XXXXXXX. Obtém-se em tagmanager.google.com, no canto superior direito do seu contentor. Deixe vazio se não usar o GTM: a extensão passa automaticamente para o loader gtag.js se estiver preenchido um Measurement ID do GA4.
• Server-side GTM URL (opcional): URL do seu loader Tag Manager server-side (por exemplo https://gtm.oseudominio.com, sem barra final). Ver a secção GTM server-side mais abaixo.

Google Analytics 4

• GA4 Measurement ID: formato G-XXXXXXXXXX. Obtém-se no GA4 em Admin → Fluxos de dados → Web. Usado como alternativa gtag.js se não houver contentor GTM configurado, e enviado para o dataLayer para as tags do GTM.
• Enviar o evento page_view automático: ativo por predefinição. Desative se preferir acionar o page_view manualmente a partir do GTM.

Consent Mode v2

• Ativar o Consent Mode v2: emite o gtag consent default antes do carregamento do GTM, com as sete categorias do Consent Mode v2. Ver Consent Mode v2 em detalhe.
• Estado de consentimento predefinido:
  • Recusado: recomendado para a UE e o RGPD. Nenhum cookie analítico ou publicitário é colocado antes da aceitação do utilizador.
  • Concedido: a reservar aos visitantes fora da UE, ou a lojas destinadas a um público profissional não abrangido pelo RGPD.
• Ativar url_passthrough: conserva os parâmetros gclid, _gl, dclid entre páginas mesmo quando os cookies são recusados. Útil para a atribuição multi-touch.
• Ativar ads_data_redaction se recusado: anonimiza os identificadores publicitários enviados ao Google Ads quando o utilizador recusa. Reduz ainda mais a superfície de tracking.

Enhanced Conversions

• Ativar as Enhanced Conversions: envia um objeto user_data com email, telefone, nome próprio, apelido, rua, localidade e código postal, todos em hash SHA-256 do lado do servidor, nas páginas confirm e finish do funil. Ver Enhanced Conversions em detalhe.

Google Shopping e Merchant Center

• Origem do item_id: determina o que a extensão envia como item_id em cada item do GA4. Este valor tem de corresponder ao campo id do seu feed do Merchant Center. Três opções:
  • Product number (SKU): recomendado, o formato mais comum nos feeds XML/CSV do Merchant Center.
  • Shopware UUID: útil se gerar o seu feed diretamente a partir da base de dados do Shopware.
  • EAN / GTIN: útil se o seu feed estiver alinhado com os códigos de barras internacionais.
• Categoria Google predefinida: valor enviado em google_product_category quando nem o produto nem a sua categoria definem uma. Formato Google (por exemplo Apparel & Accessories > Clothing).
• Marca predefinida: usada como alternativa em item_brand quando o produto não tem fabricante atribuído.

Eventos

Cada evento GA4 pode ser ativado individualmente. Desmarque os que não quiser.

• view_item: página de produto
• view_item_list: página de categoria e resultados de pesquisa
• add_to_cart: clique no botão de adicionar ao carrinho (listener JavaScript)
• remove_from_cart: remoção de uma linha do carrinho ou do offcanvas
• view_cart: página do carrinho
• begin_checkout: página de confirmação do funil
• purchase: página finish depois da encomenda
• search: página de resultados de pesquisa
• login / sign_up: submissão dos formulários de conta

Consent Mode v2 em detalhe

O Consent Mode v2 é o mecanismo oficial da Google para gerir o consentimento do utilizador. Desde março de 2024, o Google Ads exige-o aos anunciantes que visam o Espaço Económico Europeu: sem ele, perde o acesso ao remarketing e à medição das conversões.

Ordem de carregamento

A extensão garante a seguinte ordem em cada página do storefront:

1. Inicialização de window.dataLayer e do stub gtag()
2. Emissão do gtag consent default com as sete categorias do Consent Mode v2 e wait_for_update: 500
3. Emissão de url_passthrough e ads_data_redaction se estiverem ativos
4. Envio dos eventos GA4 da página (view_item, view_cart e outros) para o dataLayer
5. Carregamento do script GTM (ou gtag.js como alternativa)

Integração no banner de cookies do Shopware

A extensão decora a CookieProviderInterface e regista dois cookies virtuais nos grupos do banner nativo:

• df-gtag-analytics no grupo Estatísticas: controla analytics_storage
• df-gtag-ads no grupo Marketing: controla ad_storage, ad_user_data, ad_personalization

Quando o utilizador valida as preferências, o Shopware emite o evento CookieConfiguration_Update. O controlador JavaScript da extensão escuta esse evento, lê o valor dos dois cookies virtuais, e emite de imediato o gtag consent update correspondente.

Compatibilidade com um banner de terceiros

Se usar o Cookiebot, o CookieFirst, o OneTrust ou o Axeptio em vez do banner nativo do Shopware, tem de emitir você mesmo o gtag consent update a partir do banner de terceiros com as categorias corretas. A extensão não o impede: gere apenas o consent default inicial e a escuta do evento do Shopware.

Enhanced Conversions em detalhe

As Enhanced Conversions melhoram a precisão da medição do Google Ads enviando dados de utilizador first-party (email, telefone, nome, morada) em hash SHA-256 no momento de uma conversão. A Google volta depois a ligar essas conversões aos utilizadores Google com sessão iniciada, o que restaura tipicamente 10 a 30 % de conversões antes perdidas por causa de bloqueadores de cookies, de tracking entre dispositivos ou de mudanças de navegador.

Normalização aplicada

A extensão normaliza cada campo em conformidade com a especificação da Google antes do hash:

• Email: em minúsculas, sem espaços, e depois SHA-256
• Telefone: E.164 (prefixo de país automático a partir do ISO da morada de facturação, exemplo +351912345678), e depois SHA-256
• Nome próprio, apelido, rua, localidade: em minúsculas, sem espaços, e depois SHA-256
• Código postal: em minúsculas, sem espaços; nos EUA, truncado aos 5 primeiros dígitos antes do hash
• País: código ISO-2 em maiúsculas, sem hash

Payload do dataLayer

Nos eventos begin_checkout e purchase, a extensão envia:

{
  "event": "purchase",
  "ecommerce": { ... },
  "user_data": {
    "sha256_email_address": "...",
    "sha256_phone_number": "...",
    "address": {
      "sha256_first_name": "...",
      "sha256_last_name": "...",
      "sha256_street": "...",
      "sha256_city": "...",
      "postal_code": "...",
      "country": "PT"
    }
  }
}

Configuração no GTM

1. No seu contentor GTM, crie ou edite a sua tag Google Ads Conversion Tracking
2. Secção Include user-provided data from your website → Manual configuration
3. Crie oito variáveis Data Layer Variable a apontar para:
   • user_data.sha256_email_address → mapeada em Email (hashed)
   • user_data.sha256_phone_number → mapeada em Phone (hashed)
   • user_data.address.sha256_first_name → First name (hashed)
   • user_data.address.sha256_last_name → Last name (hashed)
   • user_data.address.sha256_street → Street (hashed)
   • user_data.address.sha256_city → City (hashed)
   • user_data.address.postal_code → Postal code
   • user_data.address.country → Country
4. Guarde e publique o contentor

Google Shopping e feed do Merchant Center

Para que o GA4 e o Google Ads consigam associar os eventos de comércio eletrónico aos seus produtos do Shopping, cada item do dataLayer tem de usar o mesmo item_id do feed do Merchant Center.

Campos enviados em cada item

• item_id: origem configurável (SKU / UUID / EAN)
• item_name: nome do produto no idioma ativo
• item_brand: nome do fabricante, ou marca predefinida se não estiver preenchido
• item_category a item_category5: breadcrumb completo a partir da categoria mais profunda
• google_product_category: ver abaixo
• price, quantity, currency
• mpn: Manufacturer Part Number se estiver preenchido no produto
• gtin: EAN se estiver preenchido
• discount: calculado a partir da diferença entre o preço riscado e o preço de venda

google_product_category por produto

Pode substituir a categoria Google Shopping de um produto ou de uma categoria através de um campo personalizado:

1. No back-office: Definições → Sistema → Campos personalizados → Criar um novo conjunto
2. Nome técnico: df_google_product_category, tipo Texto
3. Atribua esse conjunto às entidades Produto e/ou Categoria
4. Em cada produto ou categoria, preencha o valor Google (por exemplo Sporting Goods > Athletics > Football > Football Balls)

A extensão procura o valor por esta ordem: campo personalizado do produto → campo personalizado da sua categoria mais profunda → valor global predefinido da configuração.

GTM server-side

O tagging server-side permite encaminhar o tráfego do GTM por um domínio que controla, o que contorna os bloqueadores do navegador, protege os dados do utilizador, e melhora a resistência a mudanças nas políticas de cookies.

Pré-requisitos

• Um contentor GTM server-side configurado (ver a documentação da Google)
• Um domínio ou subdomínio dedicado a apontar para o seu servidor Tag Manager, por exemplo gtm.oseudominio.com

Ativação

Na configuração da extensão, secção Google Tag Manager, preencha o Server-side GTM URL com o seu domínio sem barra final:

https://gtm.oseudominio.com

O script GTM e o iframe noscript passam a apontar automaticamente para o seu servidor em vez de www.googletagmanager.com.

Verificação

Google Tag Assistant

1. Instale a extensão do Chrome Tag Assistant Companion
2. Abra tagassistant.google.com, clique em Add domain e introduza o URL do seu storefront
3. Navegue numa página de produto, adicione ao carrinho, vá ao checkout: cada passo tem de aparecer no assistente com os eventos GA4 correspondentes

GA4 DebugView

No GA4: Admin → DebugView. Os eventos aparecem aí em tempo real assim que o modo de depuração estiver ativo na extensão ou o parâmetro debug_mode=true for enviado.

Modo de depuração da extensão

Ative o Modo de depuração na configuração e abra a consola do navegador. Verá:

[DfGtag] consent update { analytics_storage: "granted", ad_storage: "denied", ... }
[DfGtag] add_to_cart { item_id: "SW10001", item_name: "...", price: 129, quantity: 1 }
[DfGtag] remove_from_cart { ... }

Checklist de validação

• Na página inicial: consent default emitido antes do script GTM (ordem das etiquetas no head)
• Numa página de produto: view_item com item_id, item_brand, item_category, google_product_category
• Ao adicionar ao carrinho: add_to_cart com o mesmo item
• No carrinho: view_cart com todos os itens
• Na página confirm: begin_checkout com user_data em hash
• Na página finish: purchase com transaction_id, value, tax, shipping, currency, items e user_data em hash
• Na aceitação dos cookies: consent update com as categorias granted

Resolução de problemas

Os eventos não aparecem no GA4 DebugView

• Verifique que o Measurement ID do GA4 está correto na configuração
• Verifique que a tag GA4 Configuration está mesmo criada e publicada no seu contentor GTM
• Verifique que o acionador da tag cobre mesmo todas as páginas (All Pages)
• Limpe a cache do Shopware e recarregue a página com hard reload (Ctrl+F5)

As Enhanced Conversions não correspondem

• Verifique que não é aplicada qualquer transformação adicional (variável SHA-256 Hash do GTM) às variáveis user_data: os valores já saem em hash
• Verifique o formato E.164 do telefone no dataLayer (com prefixo de país a começar por +)
• Verifique que o campo country está mesmo em ISO-2 maiúsculo (PT, e não Portugal)
• Espere 24 a 48 horas depois da ativação: o Google Ads precisa desse prazo para a primeira sincronização

O consent update não é emitido quando o utilizador aceita

• Confirme que o banner usado é mesmo o nativo do Shopware
• Abra a consola do navegador em modo de depuração e verifique que o evento CookieConfiguration_Update é mesmo emitido quando o utilizador valida o banner
• Verifique que os cookies df-gtag-analytics e df-gtag-ads aparecem no banner e estão mesmo marcados

O item_id não corresponde ao meu feed do Merchant Center

• Abra o seu feed XML/CSV e veja o campo <g:id> de um produto
• Na configuração da extensão, escolha a origem do item_id que produz exatamente o mesmo valor (SKU, UUID ou EAN)
• Se o seu feed usar um prefixo (por exemplo shopware_SW10001), terá de criar uma tag GTM que acrescente esse prefixo ao valor antes do envio ao Google Ads

A extensão não carrega em certas páginas

• Verifique que o sales channel em causa tem mesmo Ativar a extensão em ON na sua configuração específica
• Algumas páginas personalizadas (landing pages CMS próprias) podem não acionar os Page Loaded Events normais. Nesse caso, o contentor GTM é carregado na mesma através do pagelet do cabeçalho.