DataFirefly Server-Side: guia completo
Instalar e ligar o plugin gratuito DataFirefly Server-Side, ligar o seguimento cliente mais servidor de todo o funil WooCommerce, compreender a desduplicação por event_id, a compra no servidor à prova de bloqueio, a gestão do consentimento (incluindo o Cookie Consent v2), a fila de recuperação e a subscrição do serviço.
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
- Obtenha o ficheiro
datafirefly-serverside-2_2_0.zipa partir da sua área de cliente DataFirefly. - No back-office do WordPress, vá a Plugins → Adicionar → Carregar plugin, selecione o ZIP e clique em Instalar agora.
- 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.
- A partir da sua área de cliente DataFirefly, copie a chave de ligação (começa por
dfss_). - Cole-a no campo previsto do ecrã Ligação do plugin.
- 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.
- 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_checkouteadd_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:
- 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).