# 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…

- Página: <https://www.datafirefly.com/pt/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [en](https://www.datafirefly.com/en/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [es](https://www.datafirefly.com/es/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [de](https://www.datafirefly.com/de/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [it](https://www.datafirefly.com/it/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [pl](https://www.datafirefly.com/pl/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [nl](https://www.datafirefly.com/nl/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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
```

**Dica.** Depois do `assets:install`, o ficheiro `df-gtag-manager.js` é publicado em `public/bundles/dfgtagmanager/` e fica acessível através do asset helper do Twig. Não é necessário qualquer build de webpack ou TypeScript.

## 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](https://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](#server-side-gtm) 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](#consent-mode-v2).
- **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](#enhanced-conversions).

### 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)

**Porquê wait_for_update: 500?** Esta instrução diz à Google para esperar até 500 ms após o carregamento da página antes de emitir os hits em modo recusado, o tempo necessário para o seu banner de cookies recolher a resposta do utilizador e para a extensão enviar um `gtag consent update`. Sem esse atraso, todos os hits iniciais são emitidos em modo recusado mesmo que o utilizador aceite de imediato.

### 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

**Atenção.** A Google exige que os valores já venham em hash do lado do site: não aplique a variável _SHA-256 Hash_ do GTM a estas variáveis, elas saem já em hash da extensão. Um duplo hash tornaria a correspondência impossível.

## 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](https://developers.google.com/tag-platform/tag-manager/server-side))
- 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](https://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 `` 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.