DataFirefly Server-Side para Shopware: guia completo

Apresentação

O DataFirefly Server-Side é o conector Shopware gratuito do serviço DataFirefly Server-Side Tracking. A cada encomenda validada, a extensão constrói um evento de compra completo e envia-o de servidor para servidor, assinado com HMAC-SHA256, para o dispatcher DataFirefly alojado na UE. O serviço ingere o evento, desduplica-o e difunde-o para os seus destinos: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API e Google Ads.

A extensão é propositadamente minimalista do lado da loja: nenhuma credencial de destino fica aí guardada, nenhum script é acrescentado ao storefront, nenhuma tabela é criada. Capta, constrói, assina, envia; o resto acontece do lado do serviço.

Pré-requisitos

• Shopware 6.5.x, 6.6.x ou 6.7.x (instalação auto-alojada; o Shopware Cloud não aceita extensões de servidor)
• PHP 8.1 ou superior, consoante a sua versão do Shopware, com a extensão curl
• Uma subscrição ativa do serviço DataFirefly Server-Side Tracking para obter a sua chave de ligação

Instalação

Por carregamento de ZIP

1. Na administração do Shopware, abra Extensões → As minhas extensões → Carregar extensão e selecione o ficheiro ZIP da extensão.
2. Clique em Instalar e depois em Ativar.

Por linha de comandos

bin/console plugin:refresh
bin/console plugin:install --activate DatafireflyServerSide
bin/console cache:clear

Ligação ao serviço

Obter a sua chave de ligação

1. Inicie sessão na sua área de cliente em server-side.datafirefly.com.
2. Abra a secção Ligar a sua loja.
3. Copie a chave de ligação numa linha, no formato dfss_…. Codifica o seu identificador de tenant, o seu segredo de assinatura HMAC e o endpoint de ingestão.

Colar a chave no Shopware

1. Abra Extensões → As minhas extensões → DataFirefly Server-Side → Configuração.
2. Cole a chave no campo Chave de ligação.
3. Ative o interruptor Ativar o tracking e guarde.

É tudo: a partir da próxima encomenda validada, o evento de compra segue para o dispatcher. Uma chave em falta ou mal formada nunca é um erro bloqueante: a extensão considera simplesmente que não está configurada e não envia nada.

Configuração

• Ativar o tracking: interruptor principal. Desativado por predefinição.
• Chave de ligação: a chave dfss_… copiada da sua área de cliente.
• Exigir o consentimento de marketing: ativa a barreira de consentimento (desativada por predefinição, ver abaixo).
• Nome do cookie de consentimento: o cookie colocado pela sua ferramenta de consentimento (CMP).
• Valor do cookie de consentimento (contém): opcional; fragmento de valor esperado no cookie.

A configuração é gerida por sales channel: pode ativar o tracking numa loja e não noutra, ou usar chaves diferentes por canal.

Barreira de consentimento

O Shopware não coloca nativamente um cookie único de consentimento de marketing legível do lado do servidor. A extensão oferece portanto uma barreira genérica, desativada por predefinição: quando está ativa, o evento de compra só é enviado se o cookie configurado estiver presente no pedido do cliente e, se estiver definido um valor esperado, se o valor do cookie o contiver.

Com o DataFirefly Cookie Consent

A combinação recomendada no Shopware é a nossa extensão DataFirefly Cookie Consent (banner RGPD com Google Consent Mode v2 nativo): ative a barreira e indique o nome do cookie de consentimento colocado pelo banner (indicado na respetiva documentação). A recusa ou a ausência de consentimento de marketing bloqueia o envio, do lado do servidor, antes de qualquer transmissão.

Com outro CMP

Indique o nome do cookie que o seu CMP coloca quando o visitante aceita os cookies de marketing (por exemplo CookieConsent para o Cookiebot), e eventualmente um fragmento de valor (por exemplo marketing:true). Se o seu CMP não colocar um cookie legível do lado do servidor, ou se gerir o consentimento inteiramente a montante, deixe a barreira desativada.

Comportamento privacy-first

• Barreira ativa e nome de cookie não configurado → nada é enviado.
• Barreira ativa e cookie ausente ou vazio → nada é enviado.
• Barreira ativa e valor esperado configurado mas ausente do valor do cookie → nada é enviado.
• Pedido ausente (fluxo CLI ou headless sem pedido HTTP) → nada é enviado.

Testar a ligação

A extensão fornece um comando de consola que envia um page_view sintético para o dispatcher, sem tocar em encomendas reais:

bin/console datafirefly:serverside:test

Opções disponíveis:

• --sales-channel-id=<id>: lê a configuração de um sales channel específico (por predefinição: configuração global).
• --source-url=<url>: inclui um sourceUrl no evento de teste.

Um código HTTP 2xx confirma que a chave de ligação, a assinatura e o endpoint estão corretos, mesmo que ainda não haja qualquer destino configurado do lado do serviço.

Funcionamento técnico

O evento purchase

A extensão subscreve o evento de encomenda validada do Shopware. A cada acionamento, constrói um evento purchase com um identificador idempotente ligado à encomenda (order_<id>): se usar também tags de navegador, o serviço aplica a desduplicação cliente mais servidor e cada conversão é contada uma só vez.

Dados enviados

• Transação: valor pago, moeda, número de encomenda, produtos, quantidades, número de artigos.
• Correspondência: email, identificador de cliente, telefone, nome próprio, apelido, localidade, código postal e país da morada de facturação.
• Identificadores de navegador captados no momento da encomenda: _fbp, _fbc, _ttp e o client id do GA4 (cookie _ga).

A construção é defensiva: cada campo opcional só é acrescentado se estiver presente e válido (o dispatcher valida de forma estrita: país em 2 caracteres, moeda em 3, e assim por diante). Nos fluxos headless em que algumas associações da encomenda possam faltar, os campos correspondentes são simplesmente omitidos, nunca fabricados.

Assinatura HMAC

Cada evento é assinado com HMAC-SHA256 usando o segredo do seu tenant: os bytes assinados são exatamente os bytes enviados, com uma marca temporal verificada numa janela de 300 segundos contra reprodução. Os cabeçalhos transmitidos são o identificador de tenant, o timestamp e a assinatura. As suas credenciais Meta, GA4, TikTok, Pinterest e Google Ads ficam do lado do serviço, nunca na loja e nunca no navegador.

Fail-safe

Todo o subsistema está concebido para nunca afetar o checkout: timeouts de 2 segundos (ligação) e 4 segundos (total), todos os erros capturados e registados como warning nos logs do Shopware com o código HTTP e o número de encomenda, e nenhuma exceção chega ao funil de encomenda.

Resolução de problemas

• Nenhum evento é enviado: verifique que o interruptor está ativo para o sales channel certo, que a chave começa por dfss_ sem espaços nem quebras de linha, e que a barreira de consentimento não está ativa sem cookie configurado.
• O comando de teste falha: um código 0 com uma mensagem do curl indica um problema de rede de saída (firewall); um código 401/403 indica uma chave inválida ou regenerada: volte a copiá-la da área de cliente.
• Eventos marcados como não entregues nos logs: o código HTTP e o número de encomenda ficam registados nos logs do Shopware (canal warning). Um código 4xx assinala um payload rejeitado pela validação estrita do dispatcher; verifique o Event Inspector da sua área de cliente para os detalhes.
• Conversões duplicadas no Meta ou no GA4: confirme que as suas tags de navegador enviam o mesmo identificador de evento (order_<id>) para beneficiar da desduplicação.

Changelog

• 1.0.0 (01/07/2026): versão inicial: evento purchase server-side idempotente, assinatura HMAC-SHA256 com janela antirreprodução, chave de ligação numa linha, barreira de consentimento opt-in por cookie de CMP, configuração por sales channel, comando de consola de teste, conceção fail-safe.