# DataFirefly Google Tag Manager Pro: guia completo

> Apresentação e pré-requisitos O DataFirefly Google Tag Manager Pro envia um dataLayer GA4 ecommerce completo a partir da sua loja WooCommerce e permite gerar, com um clique, um contentor Google…

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

## Apresentação e pré-requisitos

O DataFirefly Google Tag Manager Pro envia um dataLayer GA4 ecommerce completo a partir da sua loja WooCommerce e permite gerar, com um clique, um contentor Google Tag Manager pronto a importar, já ligado a esse dataLayer. O plugin trata também do seguimento server-side (Meta Conversions API, GA4 Measurement Protocol) com deduplicação automática, do Consent Mode v2 e de um modo de injeção direta dos pixels para as lojas que não usam GTM.

- WordPress 5.8 ou superior, testado até à versão 7.0.
- WooCommerce 7.0 ou superior, testado até à versão 9.6, compatível com HPOS e com os blocos Cart/Checkout.
- PHP 7.4 ou superior.
- Multilingue (FR/EN/ES/DE/IT), compatível com Polylang e WPML.
- Nenhum seguimento é emitido no back-office, nos feeds ou no customizer.

O plugin separa dois papéis: **produz os dados** (o dataLayer GA4) e **ajuda a difundi-los** (contentor GTM gerado, pixels diretos, eventos server-side). Escolhe o modo de difusão que lhe convier.

**Idioma da interface.** O pacote de traduções do plugin cobre FR/EN/ES/DE/IT e não inclui o português. Num back-office em português, os ecrãs de definições aparecem em inglês. Isto não afeta o seguimento: os nomes dos eventos GA4 e os dados enviados são idênticos, seja qual for o idioma do back-office.

## Instalação

1. Descarregue o ficheiro `datafirefly-gtm-pro-1.1.0.zip` a partir da sua conta de cliente.
2. Na administração do WordPress, vá a **Plugins > Adicionar novo > Carregar plugin** e coloque o ficheiro.
3. Clique em **Ativar**.
4. Abra **Tag Manager Pro** no menu de administração para aceder às definições.

Na ativação, o plugin grava as suas definições por omissão. Pode depois indicar o contentor, as ligações e ativar o server-side separador a separador.

## Separador Geral: contentor e dataLayer

Este separador controla a injeção do contentor e a forma do dataLayer:

- **Identificador do contentor**: o seu ID GTM no formato `GTM-XXXXXXX`. Enquanto estiver vazio, nada é injetado do lado do GTM (o dataLayer e o modo direto continuam disponíveis).
- **Nome do dataLayer**: `dataLayer` por omissão. Altere apenas se a sua instalação o exigir.
- **Colocação**: head + body (noscript), apenas head ou apenas body.
- **Prioridade de saída**: normal ou alta (o contentor é escrito cedo no `head`).

O seguimento nunca é emitido para os administradores nem para os utilizadores com perfis excluídos (separador Avançado), nem no back-office, nos feeds RSS ou no customizer.

## Separador Ligações: as suas plataformas

Indique aqui os identificadores das plataformas que utiliza. Esta base alimenta simultaneamente o contentor GTM gerado, os pixels diretos e os eventos server-side. Deixe vazio o que não usar.

- **Google Analytics 4**: Measurement ID (`G-XXXXXXXXXX`).
- **Google Ads**: Conversion ID (`AW-XXXXXXXXX`), etiqueta de conversão de compra, remarketing dinâmico (opcional).
- **Meta**: Pixel ID, token da Conversions API, código de teste CAPI (opcional).
- **TikTok**: Pixel ID, token da Events API (opcional).
- **Pinterest**: Tag ID — **Snapchat**: Pixel ID — **LinkedIn**: Partner ID.
- **Microsoft Advertising (UET)**: Tag ID — **X**: Pixel ID.
- **Hotjar**: Site ID — **Microsoft Clarity**: Project ID.

No fim do separador, a definição **Difusão dos pixels** determina o modo: **através do Google Tag Manager** (recomendado, importa o contentor gerado) ou **injeção direta** (o próprio plugin carrega os pixels).

## Tag Pilot: gerar e importar o contentor GTM

O separador **Tag Pilot** constrói um contentor Google Tag Manager completo a partir das suas ligações e disponibiliza-o para descarregar. Gera, nomeadamente:

- a tag Google de configuração GA4 e uma tag de evento GA4 por cada evento ativado (com envio dos dados ecommerce a partir do dataLayer);
- o Conversion Linker, a conversão de compra e o remarketing dinâmico do Google Ads;
- o pixel Meta e os respetivos eventos padrão (ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, Purchase, Search);
- tags Custom HTML para TikTok, Pinterest, Snapchat, LinkedIn, Microsoft UET, X, Hotjar e Clarity;
- as Data Layer Variables e os acionadores de eventos personalizados correspondentes.

Para o importar:

1. Clique em **Descarregar o contentor GTM (.json)**.
2. No Google Tag Manager, abra **Administração > Importar contentor**.
3. Selecione o ficheiro JSON, escolha o seu espaço de trabalho e depois **Juntar** (mantém as tags existentes) ou **Substituir**.
4. Pré-visualize e depois faça **Enviar e publicar**.

Num contentor já existente, prefira **Juntar** para não eliminar as suas outras tags.

## Modo pixel direto (sem GTM)

Se não quiser depender do GTM, coloque a difusão em **injeção direta** no separador Ligações. O plugin passa a injetar os pixels de base (GA4, Meta e as restantes plataformas configuradas) e reencaminha os eventos ecommerce do dataLayer para Meta, TikTok, Pinterest, Snapchat e GA4. O mesmo dataLayer alimenta as duas abordagens.

Não ative o mesmo pixel em simultâneo através do GTM _e_ em injeção direta: corre o risco de contar duas vezes. Escolha um único modo de difusão por plataforma.

## Server-side: Meta CAPI e GA4 Measurement Protocol

No separador **Server-side**, ative o envio das compras diretamente a partir do seu servidor:

- **Meta Conversions API**: exige o Pixel ID e um token CAPI (separador Ligações). O evento Purchase é enviado com dados do cliente em hash SHA-256, os cookies `_fbp`/`_fbc`, o endereço IP e o user-agent.
- **GA4 Measurement Protocol**: exige o Measurement ID (Ligações) e um **segredo de API** (GA4 > Administrador > Fluxos de dados > Measurement Protocol).

O navegador e o servidor partilham o mesmo `event_id` determinista por encomenda (`dfgtm.purchase.`). O Meta e o GA4 usam esse identificador para contar cada conversão apenas uma vez.

Os pedidos server-side são enviados de forma não bloqueante depois do pagamento, nos estados «em processamento», «concluída» ou «pagamento concluído», uma única vez por encomenda.

**Dados pessoais.** O envio server-side transmite ao Meta e ao Google dados do cliente em hash (e-mail, telefone, endereço IP). Declare esses tratamentos e esses destinatários na sua política de privacidade e não os ative sem consentimento publicitário, nos termos do RGPD e da Lei n.º 41/2004, sob supervisão da CNPD.

## Consent Mode v2 e Enhanced Conversions

O separador **Consent** ativa o Consent Mode v2: são definidos estados de consentimento _denied_ por omissão antes do carregamento do contentor, com âmbito EEE/Reino Unido, `wait_for_update`, URL passthrough e redação dos dados publicitários. Para atualizar o consentimento conforme a escolha do utilizador, ligue a sua barra de cookies à API JavaScript fornecida:

```
// Aceitar tudo
window.dfgtmConsent.grantAll();
// Recusar tudo
window.dfgtmConsent.denyAll();
// Atualização detalhada
window.dfgtmConsent.update({ ad_storage: 'granted', analytics_storage: 'granted' });
```

As **Enhanced Conversions** do Google Ads (separador GA4 Ecommerce) acrescentam dados do cliente em hash SHA-256 no evento de compra, para melhorar a atribuição.

**Consent Mode não é conformidade legal.** O Consent Mode v2 é uma exigência do Google para continuar a usar as suas plataformas publicitárias no EEE: transmite o estado do consentimento, mas não o recolhe. Continua a precisar de uma barra de cookies que obtenha consentimento prévio e informado, exigido pelo RGPD e pela Lei n.º 41/2004 (privacidade nas comunicações eletrónicas), com a CNPD como autoridade de controlo em Portugal. É a barra que chama `window.dfgtmConsent`.

## Eventos GA4 ecommerce

O plugin envia os seguintes eventos ecommerce do GA4, cada um ativável individualmente, com objetos `items` completos (item_id a partir do SKU ou do ID, marca, categorias até 5 níveis, variante, preço, desconto):

- `view_item_list`, `view_item`, `select_item`
- `add_to_cart`, `remove_from_cart`, `view_cart`
- `begin_checkout`, `add_shipping_info`, `add_payment_info`
- `purchase` (deduplicado: disparado uma única vez por encomenda, mesmo em caso de recarregamento), `search`

## Hooks para programadores

O plugin expõe filtros nos pontos-chave para estender o comportamento sem alterar o núcleo:

- `dfgtm_export_container`: alterar o contentor GTM gerado antes da codificação.
- `dfgtm_meta_capi_payload` e `dfgtm_ga4_mp_payload`: ajustar os payloads server-side.
- `dfgtm_connections_registry`: acrescentar ou alterar destinos.
- `dfgtm_purchase_push` e `dfgtm_build_item`: personalizar os dados de compra e a construção dos items.

## FAQ e resolução de problemas

### Não é injetado nada do lado do GTM

Verifique se o identificador do contentor (`GTM-XXXXXXX`) está preenchido no separador Geral e se não está autenticado com um perfil excluído. O dataLayer e o modo direto funcionam mesmo sem contentor GTM.

### As conversões são contadas duas vezes no Meta

Confirme que não está a carregar o mesmo pixel pelo contentor GTM e em injeção direta ao mesmo tempo. O server-side e o navegador são deduplicados automaticamente pelo `event_id`, por isso não são fonte de duplicação.

### O evento de compra não chega em server-side

Verifique se a opção correspondente está ativada no separador Server-side e se os identificadores exigidos estão preenchidos: Pixel ID + token CAPI para o Meta, Measurement ID + segredo de API para o GA4. O envio ocorre uma única vez por encomenda.

### A tag GA4 não envia os dados ecommerce

No contentor gerado, as tags de evento GA4 leem os dados ecommerce a partir do dataLayer. Se construiu as suas tags manualmente, ative «Enviar dados de ecommerce» e escolha «dataLayer» como fonte.

### Os valores são enviados em euros?

A moeda transmitida é a da encomenda WooCommerce. Numa loja portuguesa em euros, os eventos saem em `EUR`; numa loja multimoeda, cada evento leva a moeda usada no pagamento. Confirme que a moeda de reporte do GA4 está coerente com o que espera ver nos relatórios.

### O que acontece na desinstalação?

Se a opção correspondente estiver ativada no separador Avançado, as definições e os metadados de seguimento das encomendas são eliminados. Caso contrário, são conservados para uma eventual reinstalação.