# 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…

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

## 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.

**Numa frase:** três exigências regulamentares cobertas numa única extensão: Consent Mode v2 (março de 2024), equivalência Aceitar/Recusar (orientações CEPD e CNIL), prova de consentimento (RGPD).

## 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
```

**Bom saber:** o JavaScript da extensão é entregue pré-compilado em `Resources/app/storefront/dist/`. **Não precisa** de executar o `build-storefront.sh` para que o banner funcione.

## 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

**Ordem de execução no head:** 1) bloco `gtag consent default` com todos os sinais a `denied`; 2) loader do GTM se configurado; 3) loader do GA4 se configurado (e GTM vazio); 4) carregamento do banner e sinais atualizados por `gtag consent update` assim que o visitante clica.

### 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

**Com Cloudflare:** a deteção é instantânea e fiável, o cabeçalho `CF-IPCountry` é acrescentado gratuitamente em cada pedido. **Sem Cloudflare:** recurso ao `Accept-Language` para adivinhar o país a partir da locale do navegador (menos fiável mas funcional).

## 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
```

**Atenção:** sem o sinalizador `--keep-user-data`, o registo de auditoria (dfcc_consent_log) perde-se. Se prevê reinstalar mais tarde, use sempre `--keep-user-data`.

## 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