DataFirefly Server-Side: guia completo

Apresentação

O DataFirefly Server-Side é o conector PrestaShop gratuito do serviço DataFirefly Server-Side Tracking. A cada encomenda validada, o módulo constrói um evento de compra completo e envia-o de servidor para servidor, assinado HMAC-SHA256, para o dispatcher DataFirefly alojado na UE (Alemanha). O serviço difunde depois o evento para os seus destinos configurados: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API e Google Ads.

A repartição de papéis é simples: o módulo capta e assina, o serviço ingere, desduplica e difunde. O módulo é gratuito; a difusão exige uma subscrição do serviço (Starter a partir de 39 €/mês).

Pré-requisitos

• PrestaShop 1.7.6 ou superior, 8.x ou 9.x
• PHP 7.4 ou superior, com a extensão cURL (presente na quase totalidade dos alojamentos)
• Uma conta DataFirefly Server-Side Tracking ativa: subscreva em server-side.datafirefly.com
• Recomendado: o nosso módulo DataFirefly Cookie Manager (banner tarteaucitron conforme ao RGPD com Google Consent Mode v2) para a gate de consentimento nativa

Instalação

1. Transfira o ZIP do módulo a partir da sua conta DataFirefly.
2. No back-office do PrestaShop, abra Módulos > Gestor de módulos > Instalar um módulo e envie o ficheiro datafirefly_serverside.zip.
3. Clique em Instalar. O módulo regista-se no hook de validação de encomenda; não é necessário nenhum override nem alteração de tema.

Na instalação, o tracking está desativado e a exigência de consentimento está ativa: nada parte enquanto não tiver configurado e ativado o módulo.

Obter as suas credenciais

1. Inicie sessão na sua área de cliente DataFirefly (ou subscreva se ainda não o fez).
2. Abra a secção Ligar a sua loja do seu site.
3. Copie os três valores apresentados: o Tenant ID (no formato shop_asualoja_xxxx), o segredo HMAC (chave de assinatura de 64 caracteres) e o endpoint de eventos.

Configuração

Abra Módulos > Gestor de módulos > DataFirefly Server-Side > Configurar. O formulário tem cinco definições:

• Ativar o tracking: o interruptor principal. Enquanto estiver em Não, nenhum evento é enviado.
• Tenant ID: o identificador da sua loja no serviço, copiado a partir da sua área de cliente.
• Segredo HMAC: a chave de assinatura de 64 caracteres. Cada evento é assinado com esta chave antes do envio.
• Events endpoint: o URL de ingestão do dispatcher. O valor por defeito serve na quase totalidade dos casos; só o altere se a sua área de cliente indicar outro.
• Exigir o consentimento: ativo por defeito. Quando está ativo, a compra só é transmitida se o visitante tiver dado um consentimento de marketing (ver abaixo). Desative-o apenas se gerir o consentimento a montante com outro dispositivo.

Guarde e passe ao teste.

Testar a ligação

Clique em Enviar um evento de teste no formulário de configuração. O módulo envia um page_view sintético, assinado, para o dispatcher, sem tocar nas encomendas reais.

• «Evento de teste entregue» (HTTP 200): o seu Tenant ID, o seu segredo e o seu endpoint estão corretos. A sua loja está ligada, mesmo que ainda não haja nenhum destino configurado do lado do serviço.
• «Evento de teste falhou»: o código HTTP e a mensagem do dispatcher são apresentados para diagnóstico (ver Resolução de problemas).

O consentimento (RGPD)

Quando Exigir o consentimento está ativo, o módulo lê, diretamente do lado do servidor e no momento da validação da encomenda, o cookie de consentimento no formato tarteaucitron colocado pelo nosso módulo DataFirefly Cookie Manager (Google Consent Mode v2). O nome do cookie é retomado automaticamente da configuração do Cookie Manager (por defeito tarteaucitron).

A compra é transmitida se o visitante tiver consentido em pelo menos um serviço publicitário: Meta Pixel, Google Ads, TikTok Pixel ou LinkedIn Insight. A abordagem é privacy-first: cookie ausente ou ilegível = nenhum envio.

Se gerir o consentimento com outro dispositivo, desative Exigir o consentimento e aplique a sua própria lógica a montante: cabe então ao seu dispositivo garantir que nenhuma encomenda provém de um visitante que não consentiu.

O que é enviado

A cada encomenda validada, o módulo constrói um evento purchase com:

• Transação: montante pago, moeda ISO, referência da encomenda, produtos (id, nome, quantidade, preço unitário com IVA) e número total de artigos.
• Dados de correspondência: e-mail e identificador do cliente, telefone, nome próprio, apelido, cidade, código postal e país ISO da morada de faturação (recurso à morada de entrega).
• Identificadores do navegador capturados no momento da encomenda: _fbp e _fbc (Meta), _ttp (TikTok) e o client id GA4 extraído do cookie _ga.

Cada campo opcional só é acrescentado se estiver presente e for válido: o dispatcher valida de forma estrita, e um evento bem formado é um evento entregue. O identificador do evento está alinhado com a encomenda (order_ID), de forma idempotente: é ele que permite a desduplicação cliente + servidor do lado das plataformas se usar também tags no navegador.

Do lado do transporte, cada pedido leva três cabeçalhos: o tenant, o carimbo temporal (verificado numa janela anti-replay de 300 segundos) e a assinatura HMAC-SHA256 do corpo exato do pedido. As suas credenciais Meta, GA4, TikTok, Pinterest e Google Ads ficam na sua área DataFirefly: nem a loja nem o navegador as veem.

Acompanhar os seus eventos do lado do serviço

Na sua área de cliente, o Event Inspector mostra-lhe os eventos um a um, com os dados pessoais mascarados (conforme ao RGPD). Verifica aí o que é realmente entregue a cada destino. A disponibilidade das plataformas pode ser consultada a qualquer momento na página de estado pública.

Resolução de problemas

O evento de teste falha com «not_configured»

Um dos três campos (Tenant ID, segredo, endpoint) está vazio. Copie de novo os três valores a partir da sua área de cliente e guarde antes de testar de novo.

O evento de teste falha em HTTP 401 ou 403

A assinatura é rejeitada: o segredo HMAC não corresponde ao tenant, ou o Tenant ID está errado. Copie de novo os dois valores sem espaços nem quebras de linha. Verifique também que o relógio do seu servidor está correto (NTP): um desvio superior a 300 segundos faz falhar a janela anti-replay.

O evento de teste falha com «curl: …» ou HTTP 0

O seu servidor não consegue contactar o dispatcher: firewall de saída, DNS ou proxy. Autorize as ligações HTTPS de saída para o endpoint indicado na sua área de cliente.

O teste passa, mas não chega nenhuma encomenda

• Verifique que Ativar o tracking está em Sim.
• Se Exigir o consentimento estiver ativo, só as encomendas de visitantes que consentiram num serviço publicitário são transmitidas. Faça uma encomenda de teste depois de aceitar os cookies publicitários no banner.
• Consulte Parâmetros avançados > Registos no back-office: cada falha de entrega é aí registada com o código HTTP e o identificador da encomenda (prefixo [DataFirefly SS]).

As conversões são contadas duas vezes

Impossível do lado do módulo: o identificador do evento é idempotente por encomenda. Se usar também tags no navegador fora do serviço, certifique-se de que enviam o mesmo identificador de evento (order_ID) para que as plataformas desdupliquem.

Desinstalação

A desinstalação elimina toda a configuração do módulo (tenant, segredo, endpoint, definições). Não é criada nenhuma tabela na base de dados: o módulo não guarda nada além da sua configuração.