# DataFirefly Server-Side: guia completo

> Guia completo de instalação, ligação e utilização do conector gratuito DataFirefly Server-Side para WooCommerce: seguimento cliente mais servidor, desduplicação, compra do lado do servidor, consentimento e subscrição do serviço.

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

O DataFirefly Server-Side é o conector WooCommerce **gratuito** do serviço _DataFirefly Server-Side Tracking_. O plugin capta os eventos da sua loja e assina-os; o serviço difunde-os do lado do servidor para as suas plataformas publicitárias e de análise. Este guia cobre a instalação, a ligação, o funcionamento do funil cliente mais servidor, a desduplicação, a compra no servidor, a escolha dos destinos de cliente, a gestão do consentimento, a fiabilidade e a subscrição.

**Modelo de plugin gratuito mais serviço pago.** O plugin não custa nada e vai continuar gratuito. Para _enviar_ realmente os seus eventos, é preciso uma subscrição do serviço DataFirefly Server-Side (a partir de 39 €/mês), que assegura a ingestão e a difusão do lado do servidor.

## Requisitos

- WordPress 5.8 ou superior
- WooCommerce 5.0 ou superior (compatível com HPOS, High-Performance Order Storage)
- PHP 7.4 ou superior
- Um cron do WordPress funcional (ou um verdadeiro cron de sistema) para a fila de recuperação e o envio diferido
- Uma subscrição DataFirefly Server-Side para obter a sua chave de ligação

## Instalação

1. Obtenha o ficheiro `datafirefly-serverside-2_2_0.zip` a partir da sua área de cliente DataFirefly.
2. No back-office do WordPress, vá a **Plugins → Adicionar → Carregar plugin**, selecione o ZIP e clique em _Instalar agora_.
3. Ative a extensão. Aparece um novo menu **DataFirefly Server-Side** na administração.

## Ligação com uma única chave

O módulo configura-se com uma única chave de ligação, que ativa ao mesmo tempo o seguimento no cliente e o seguimento no servidor.

1. A partir da sua área de cliente DataFirefly, copie a **chave de ligação** (começa por `dfss_`).
2. Cole-a no campo previsto do ecrã _Ligação_ do plugin.
3. Clique em **Ligar**. O módulo ativa o seguimento no cliente e no servidor, envia um evento de teste ao dispatcher e coloca as tags de cliente para os destinos configurados.
4. Verifique que o estado passa a **Ligado ✓** e use o botão _Testar o evento_ para confirmar a receção.

A chave `dfss_…` codifica o seu tenant, um segredo e o endpoint do dispatcher. Está restrita aos hosts `datafirefly.com` em HTTPS: uma chave que aponte para outro domínio é recusada.

### Modo avançado (introdução manual)

Se preferir não usar a chave única, o **modo avançado** permite indicar manualmente o tenant, o segredo e o endpoint. Reserve-o para configurações específicas: o modo de chave única cobre a quase totalidade dos casos.

## Funil completo cliente mais servidor

O plugin acompanha todo o funil do lado do navegador, enquanto a conversão de compra parte do lado do servidor.

- **Do lado do navegador:** `page_view`, `view_content` (visualização de produto), `add_to_cart`, `initiate_checkout` e `add_payment_info`.
- **Do lado do servidor:** `purchase`, desencadeado a partir dos hooks de encomenda do WooCommerce.

As duas camadas partilham o mesmo identificador de evento para permitir a desduplicação.

### Eventos de merchandising (desde a v2.1.1)

O tracker cobre também o merchandising do seu catálogo: `view_item_list` (visualização de uma lista de produtos, categoria ou resultados de pesquisa), `select_item` (clique num produto de uma lista), `view_promotion` e `select_promotion` (visualização e clique numa promoção). O contexto associado (identificador e nome da lista, identificador e nome da promoção, criativo e posição) é transmitido ao server-side para enriquecer as suas análises de percurso.

### Desduplicação por event_id

Em cada encomenda, o evento de cliente e o evento de servidor levam o mesmo `event_id`, construído sobre o identificador da encomenda (por exemplo `order_1042`). A Meta, o GA4 e as outras plataformas apoiam-se nele para **contar cada conversão apenas uma vez**. Recupera assim as conversões que o navegador deixa escapar, sem contagem dupla.

## Escolher os destinos de cliente (Meta, GA4, TikTok)

Desde a versão 2.2.0, cada tag de cliente pode ser ativada ou desativada individualmente nas definições do plugin, linha **Destinos de cliente**:

- **Meta** (píxel do Facebook, `fbevents.js`)
- **Google Analytics 4** (`gtag.js`)
- **TikTok** (píxel do TikTok)

Um destino desassinalado **nunca carrega o seu script de terceiros** no navegador dos seus visitantes e **nunca coloca os seus cookies**. Não usa a Meta? Desassinale-a: menos JavaScript, menos pedidos, uma página mais rápida e mais sóbria. Os destinos não configurados na sua conta DataFirefly são assinalados no ecrã de definições.

Estas caixas dizem respeito apenas às _tags de cliente_. A difusão do lado do servidor para a Meta CAPI, o GA4, o TikTok, o Pinterest e o Google Ads continua a ser comandada pela configuração da sua conta na área de cliente DataFirefly. Note que, ao desativar o GA4, o cookie `_ga` deixa de ser colocado pelo plugin, o que reduz a qualidade de correspondência do GA4 do lado do servidor, o que é coerente se não usar o GA4.

## Compra do lado do servidor: fiável e infalsificável

A conversão de compra é desencadeada pelos hooks de encomenda do WooCommerce (pagamento concluído, em processamento, concluída), de forma **idempotente**: um bloqueio (`_dfss_sent`) garante que uma mesma compra nunca é enviada duas vezes, mesmo que vários hooks disparem.

- Como o evento parte do servidor, nenhum bloqueador de publicidade nem ITP o consegue impedir.
- Inversamente, o endpoint público de recolha (beacon) **exclui propositadamente** o evento `purchase`: é impossível injetar uma falsa compra a partir do navegador para inflacionar as suas receitas na Meta ou no GA4.
- O contexto do evento (valor, moeda, produtos) é autoritativo do lado do servidor: o navegador não «adivinha» nada.

Para tornar a atribuição fiável mesmo através de um gateway de pagamento com redirecionamento, o plugin captura no checkout os cookies `_fbp`, `_fbc`, `_ga` e `_ttp`, associa-os à encomenda, e coloca cookies first-party de click-id (90 dias) para transportar o `fbc`, o `ttclid` e o `gclid` até à compra.

## Gestão do consentimento

O **gate de consentimento está ativo por predefinição**: nada é enviado enquanto o consentimento de marketing não for concedido.

### Compatibilidade nativa com o Cookie Consent v2

O plugin deteta nativamente o módulo **DataFirefly Cookie Consent, RGPD e Google Consent Mode v2** e lê o seu cookie de consentimento (`dfcc_consent`) diretamente no servidor. Se a categoria _marketing_ for recusada, o evento é descartado, diga o navegador o que disser. É a combinação recomendada: banner, Consent Mode v2 e tracking server-side falam a mesma linguagem.

### Outras soluções de consentimento

Na ausência do Cookie Consent v2, o plugin suporta também o **WP Consent API**, o **Complianz**, o **Cookiebot** e o **IAB TCF v2**. Pode manter o seu banner atual e ligar o seguimento a ele.

## Fiabilidade: fila de recuperação e registo de atividade

Um evento que não conseguiu ser entregue não se perde: é colocado em fila de espera e **reenviado automaticamente** por um cron a cada 5 minutos.

O **registo de atividade** mostra em tempo real, sem jargão, o que foi entregue, o que está em fila e o que foi rejeitado, com o código HTTP e o número de tentativas. É o seu primeiro reflexo de diagnóstico.

O cron do WordPress só é executado com tráfego. Numa loja de baixo tráfego, configure um verdadeiro cron de sistema que chame o `wp-cron.php`, para que a fila de recuperação se esvazie com regularidade.

## Segurança

- Sem segredos no navegador: só os identificadores públicos (píxel, measurement id) são expostos do lado do cliente.
- O segredo de assinatura e os seus identificadores de destino ficam do lado do servidor.
- Cada evento é assinado em HMAC antes de chegar ao dispatcher, alojado na UE (Alemanha).
- O plugin é distribuído sob licença GPLv2 ou posterior e segue os padrões de codificação do WordPress.

## Subscrição do serviço DataFirefly Server-Side

O plugin capta e assina; o serviço _DataFirefly Server-Side Tracking_ ingere e difunde do lado do servidor para cinco destinos: **Meta CAPI, GA4 (Measurement Protocol), TikTok Events API, Pinterest Conversions API e Google Ads**. O dispatcher está alojado na Alemanha, a ingestão é assinada em HMAC, os dados pessoais são mascarados e o disparo respeita o consentimento. Uma única integração, uma fatura consolidada e a possibilidade de vários sites.

Descubra as ofertas e subscreva em [server-side.datafirefly.com](https://server-side.datafirefly.com/):

- **Starter**: 39 €/mês, 1 site, até 500 mil eventos
- **Growth**: 119 €/mês, 5 sites, até 2 milhões de eventos
- **Scale**: 349 €/mês, 20 sites, até 10 milhões de eventos

## Resolução de problemas

### O estado continua em «Não ligado»

Verifique que a chave começa mesmo por `dfss_` e que foi copiada por inteiro. Uma chave que aponte para outro domínio que não `datafirefly.com` (HTTPS) é recusada. Tente de novo o botão _Testar o evento_.

### A compra não é recebida

A compra parte dos hooks de encomenda: certifique-se de que a encomenda atinge um estado de pagamento (concluído, em processamento, concluída). Consulte o registo de atividade para ver se o evento está em fila ou foi rejeitado, e verifique o cron se houver eventos parados.

### O script da Meta (ou do GA4, do TikTok) não carrega

Duas causas possíveis: o destino está desassinalado em **Destinos de cliente** (comportamento pretendido desde a v2.2.0), ou não está configurado na sua conta DataFirefly, o que o ecrã de definições indica. Depois de uma alteração do lado da conta, use o botão _Atualizar os identificadores de destino_.

### Conversões contadas duas vezes

Verifique que nenhum outro plugin de tracking está já a enviar um `purchase` concorrente sem `event_id` partilhado. Só com o DataFirefly Server-Side, o `event_id` baseado na encomenda garante a desduplicação.

### Nada parte apesar de o consentimento parecer dado

O gate está ativo por predefinição. Verifique que a categoria _marketing_ está mesmo aceite na sua solução de consentimento, e que esta é detetada (Cookie Consent v2, WP Consent API, Complianz, Cookiebot ou IAB TCF v2).

Precisa de ajuda? Contacte o suporte DataFirefly a partir da sua área de cliente, juntando uma captura do registo de atividade (código HTTP e número de tentativas).