DataFirefly Cookie Consent para Shopware 6: documentação

Apresentação

O DataFirefly Cookie Consent é uma extensão Shopware 6 que substitui integralmente o banner de cookies nativo por um sistema moderno conforme ao RGPD e às orientações das autoridades europeias (CNPD, CNIL, Garante Privacy), com Google Consent Mode v2 nativo, auditoria real dos trackers, e registo de auditoria protegido criptograficamente para a prova de consentimento.

Pré-requisitos e compatibilidade

• Shopware 6.6.x ou 6.7.x (constraint composer ~6.6.0||~6.7.0)
• PHP 8.2 ou superior
• Instalação auto-alojada (a extensão não funciona no Shopware Cloud SaaS)
• HTTPS recomendado em produção (o sinalizador de cookie Secure só é acrescentado em HTTPS)
• Cloudflare recomendado para uma deteção EEE ideal (CF-IPCountry), mas não obrigatório

Instalação

Instalação por carregamento de ZIP (recomendada)

1. Transfira o ficheiro DataFireflyCookieConsent-1.0.1.zip a partir da sua conta de cliente DataFirefly
2. Na administração do Shopware, vá a Extensões → As minhas extensões → Carregar uma extensão
3. Selecione o ficheiro ZIP e confirme
4. Clique em Instalar e depois em Ativar
5. Limpe a cache: bin/console cache:clear
6. Recompile o tema: bin/console theme:compile

Instalação por Composer (CLI)

cd /var/www/shopware
# Descomprimir o ZIP em custom/plugins/
unzip DataFireflyCookieConsent-1.0.1.zip -d custom/plugins/

# Atualizar a lista, instalar, ativar
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile

Configuração geral

Toda a configuração se faz a partir de Extensões → As minhas extensões → DataFirefly Cookie Consent → ⋮ → Configurar. As opções podem ter âmbito por sales channel (selecione o canal no topo da página de configuração).

Secção Geral

• Enabled: ativa ou desativa completamente a extensão (o banner nativo do Shopware volta a assumir se estiver desativada)
• Policy version: versão da sua política de privacidade (por predefinição 1.0). Incremente-a quando alterar a política para forçar um novo consentimento
• Policy URL: URL da sua página de política de privacidade (apresentado como ligação no banner)
• Respect Do Not Track: se ativo, recusa automaticamente os cookies aos visitantes com o DNT ativo no navegador

Secção Banner

• Layout: bar (barra de largura total), card (cartão de canto discreto) ou modal (janela centrada bloqueante)
• Position: bottom ou top
• Theme: light, dark ou auto (segue o prefers-color-scheme)
• Accent color: cor de destaque personalizável através de um seletor de cores (por predefinição #3b82f6)
• Show floating button: mostra o botão flutuante persistente no canto inferior esquerdo para reabrir as preferências

Secção Categorias

Ative ou desative individualmente as 3 categorias opcionais. A categoria Estritamente necessários está sempre ativa.

• Functional enabled: cookies de personalização, preferências do utilizador
• Analytics enabled: Google Analytics 4, Matomo, medição de audiência
• Marketing enabled: tracking publicitário, retargeting

Google Consent Mode v2

A extensão imprime automaticamente o bloco gtag('consent', 'default', ...) em prioridade 1 no head do storefront, com os 7 sinais exigidos desde março de 2024: ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, security_storage.

Secção Consent Mode

• GTM Container ID: o seu ID do GTM (GTM-XXXXXXX). Se estiver preenchido, a extensão carrega automaticamente o GTM depois do bloco default. Deixe vazio para não carregar o GTM
• GA4 Measurement ID: o seu ID do GA4 (G-XXXXXXXXXX). Se estiver preenchido e o GTM vazio, a extensão carrega o GA4 de forma autónoma. Deixe vazio se carregar o GA4 através do GTM
• URL passthrough: preserva os parâmetros de URL para as conversões do Ads quando o consentimento é recusado (recomendado)
• Ads data redaction: anonimiza os dados de ads quando o consentimento é recusado (recomendado)
• Wait for update (ms): tempo de espera antes do primeiro ping GA4/Ads, para dar tempo ao visitante de responder ao banner. Por predefinição 500 ms

Mapeamento categorias → sinais

Quando o visitante clica num botão, as categorias selecionadas são automaticamente mapeadas para os sinais do Consent Mode v2:

• Functional → functionality_storage, personalization_storage
• Analytics → analytics_storage
• Marketing → ad_storage, ad_user_data, ad_personalization
• Necessary → security_storage (sempre granted)

Deteção EEE e modo eeaOnly

A extensão deteta automaticamente o país do visitante para determinar se está abrangido pelo RGPD (31 países UE/EEE, mais Reino Unido e Suíça).

Secção EEE

• EEA only mode: se ativo, o banner só aparece aos visitantes detetados como estando no EEE. Os restantes visitantes recebem um consentimento implícito e não veem nada
• Cloudflare support: se ativo (true por predefinição), lê em prioridade os cabeçalhos CF-IPCountry e CF-Connecting-IP acrescentados pela Cloudflare

Auditoria dos trackers

A partir do módulo de administração (Marketing → DataFirefly Cookie Consent → Auditoria), lance uma auditoria ao seu URL para detetar os trackers realmente presentes e obter uma pontuação de conformidade de 0 a 100.

Como lançar uma auditoria

1. Vá a Marketing → DataFirefly Cookie Consent → Auditoria
2. Preencha o URL a auditar (por predefinição o URL atual da sua loja)
3. Clique em Lançar a auditoria
4. O resultado aparece em poucos segundos: pontuação visual (anel cónico), trackers detetados, extensões de risco, problemas classificados como critical/warning/info

O que é detetado

• 23 trackers JavaScript: Google Analytics 4, Google Tag Manager, Meta Pixel, TikTok Pixel, LinkedIn Insight Tag, Pinterest Tag, Snapchat Pixel, Twitter X Pixel, Bing UET, Matomo, Microsoft Clarity, Hotjar, Mixpanel, Plausible, HubSpot, Intercom, Crisp, Tawk, embed do YouTube, embed do Vimeo, Stripe Elements e outros
• 11 extensões Shopware de risco: consulta à base de dados para detetar as extensões de servidor conhecidas por colocarem cookies não conformes

Interpretação da pontuação

• 90 a 100: excelente, conformidade ideal
• 70 a 89: bom, alguns pequenos ajustes a fazer
• 50 a 69: médio, problemas critical a tratar
• 0 a 49: não conforme, ação urgente necessária

Registo de auditoria e exportações

Cada evento de consentimento (accept_all, reject_all, custom, withdraw) fica registado na tabela dfcc_consent_log com data e hora ao milissegundo, sales channel, idioma, versão da política, snapshot das categorias e sinais do Consent Mode v2, IP duplamente protegido e user agent.

Proteção do IP do visitante

Dupla proteção única:

• Hash SHA-256 com um sal aleatório de 64 caracteres gerado na instalação e nunca exposto. Matematicamente irreversível.
• Versão truncada em paralelo: IPv4 → último octeto a zero (rede de classe C), IPv6 → prefixo de 64 bits. Permite a análise geográfica sem reidentificação.

Consultar o registo

1. Vá a Marketing → DataFirefly Cookie Consent → Registo
2. Filtre por tipo de evento e intervalo de datas se for necessário
3. A tabela pagina 50 entradas por página

Exportar como prova para a autoridade de controlo

A partir da página Registo, clique em Exportar CSV ou Exportar JSON: o ficheiro transferido contém todas as entradas correspondentes aos filtros ativos.

• CSV: BOM UTF-8 e separador ponto e vírgula (abre diretamente no Excel em português, francês ou italiano)
• JSON: pretty (indentado) com unicode preservado

Secção Registo

• Retention days: duração de conservação em dias (1825 por predefinição = 5 anos, recomendação da CNIL, adequada como referência na UE)
• Uma tarefa agendada do Shopware elimina automaticamente todas as noites as entradas mais antigas

API JavaScript pública

A extensão expõe uma API global window.dfcc utilizável a partir de qualquer código JavaScript do seu site.

// Abrir o banner e a janela de preferências
window.dfcc.open();

// Aceitar / recusar tudo por código
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Retirar o consentimento (apaga cookie e localStorage)
window.dfcc.withdraw();

// Obter o estado atual
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// ou null se ainda não foi dado qualquer consentimento

// Verificar o consentimento para uma categoria
if (window.dfcc.hasConsent('analytics')) {
    // carregar o seu script de analytics
}

// Diagnosticar o estado do armazenamento (depuração)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Versão da extensão
console.log(window.dfcc.version);
// → "1.0.1"

Eventos DOM

A extensão emite dois eventos personalizados em window:

// Emitido assim que a extensão é inicializada na página
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Emitido a cada alteração de consentimento (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);
    
    // Carregar um script de terceiros se a categoria marketing for aceite
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});

Multicanal (sales channels)

Toda a configuração pode ter âmbito por sales channel. Para configurar um canal específico de forma diferente dos outros:

1. Vá a Extensões → As minhas extensões → DataFirefly Cookie Consent → Configurar
2. No topo da página, selecione o sales channel a configurar
3. Altere as opções: só as opções alteradas nesta vista substituem a configuração predefinida

Personalização avançada

Textos do banner

O texto do banner usa os snippets normais do storefront do Shopware. Para personalizar um texto, crie a sua própria extensão de snippets e sobreponha as chaves dfcc.banner.* e dfcc.modal.*:

<!-- custom-snippets/storefront.pt-PT.json -->
{
    "dfcc": {
        "banner": {
            "title": "O seu título personalizado",
            "body": "A sua descrição personalizada."
        }
    }
}

Estilo CSS

Todos os elementos do banner usam classes CSS com o prefixo .dfcc- (por exemplo .dfcc-banner, .dfcc-modal, .dfcc-button--primary). Sobreponha-as a partir do seu tema ou através da extensão Custom Code Manager DataFirefly.

Resolução de problemas

O banner não aparece

• Verifique que Enabled está mesmo marcado na configuração da extensão
• Verifique que o modo EEA only não está ativo enquanto testa a partir de fora do EEE
• Verifique na consola das DevTools: window.dfcc tem de estar definido. Se não estiver, o JS não está carregado → execute de novo bin/console theme:compile
• Limpe os cookies do domínio em DevTools → Application → Cookies → Clear all, e recarregue

O banner volta a aparecer em cada página (erro da v1.0.0 corrigido na v1.0.1)

1. Atualize para a v1.0.1 se ainda não o fez
2. Execute window.dfcc.debug() na consola para diagnosticar
3. Se cookieRaw estiver vazio mas localStorageRaw preenchido: o seu navegador bloqueia a escrita do cookie (verifique o protocolo HTTPS e os sinalizadores Secure/SameSite)
4. Se ambos estiverem vazios mas um consentimento tiver sido clicado: abra um pedido de suporte com o resultado de debug()

Conversões do Google Ads não registadas

• Verifique que o GTM Container ID ou o GA4 Measurement ID está mesmo preenchido
• Verifique em DevTools → Network: o bloco gtag consent default tem de ser executado antes do carregamento do GTM/GA4
• Ative o url_passthrough e o ads_data_redaction para preservar as conversões dos visitantes que recusaram
• Verifique em GA4 → Admin → Data collection → Consent Mode que os parâmetros são reconhecidos

As exportações CSV abrem mal no Excel

O ficheiro é gerado com BOM UTF-8 e separador ponto e vírgula (norma do Excel em português e francês). Se o seu Excel esperar uma vírgula (versões inglesas), use a exportação JSON em alternativa, ou importe por Dados → A partir de um ficheiro CSV e indique o separador.

Desinstalação

Para desativar temporariamente:

bin/console plugin:deactivate DataFireflyCookieConsent

Os dados ficam na base de dados, o banner nativo do Shopware volta a assumir.

Para desinstalar completamente:

bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# ou para eliminar também a tabela dfcc_consent_log e a configuração:
bin/console plugin:uninstall DataFireflyCookieConsent

Changelog

1.0.1, 23 de maio de 2026 (correção da persistência)

• Reescrita completa da camada de armazenamento do lado do JavaScript
• Escrita direta do cookie com Max-Age e Expires combinados
• Sinalizador Secure acrescentado apenas em HTTPS
• Alternativa automática em localStorage se a escrita do cookie falhar
• Autoverificação escrita→leitura com registo na consola em caso de dessincronização
• Novo método window.dfcc.debug()

1.0.0, 23 de maio de 2026 (lançamento inicial)

• Compatibilidade com Shopware 6.6 e 6.7
• Banner v3 com 3 layouts, 2 posições, 3 temas
• Google Consent Mode v2 nativo com os 7 sinais
• Auditoria real dos trackers (23 trackers e 11 extensões de risco)
• Registo de auditoria com IP duplamente protegido (SHA-256 e truncagem)
• Deteção EEE inteligente (31 países, mais UK e CH, suporte a Cloudflare)
• Módulo de administração em Vue 3 (mt-*): painel, auditoria, registo
• Exportações CSV e JSON
• Snippets de storefront e de administração em 5 idiomas