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

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

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.

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.

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.<id>). O Meta e o GA4 usam esse identificador para contar cada conversão apenas uma vez.

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.

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.