# Centro de Notificações para Shopware 6: instalação, configuração e documentação técnica

> Apresentação O Centro de Notificações DataFirefly acrescenta um sino de notificações no cabeçalho do storefront do Shopware 6, mesmo ao lado do carrinho. Um selo vermelho indica o número de…

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

## Apresentação

O Centro de Notificações DataFirefly acrescenta um **sino de notificações** no cabeçalho do storefront do Shopware 6, mesmo ao lado do carrinho. Um selo vermelho indica o número de mensagens por ler (apresentado como «9+» acima de nove) e um painel pendente mostra os seus anúncios, novos produtos e códigos promocionais.

A extensão gere três tipos de notificações: os **anúncios** escritos manualmente, as **notificações de produto** criadas automaticamente a cada novo produto (imagem e ligação resolvidas em tempo real) e os **códigos promocionais** com um botão «Copiar». Cada notificação pode ser agendada, segmentada por grupo de clientes e por canal de venda, priorizada e acompanhada através de KPI de visualizações e cliques.

Uma única extensão, um único ZIP, compatível com **Shopware 6.5, 6.6 e 6.7**, incluindo a administração baseada em Vite da 6.7, entregue pré-compilada sem passo de build.

## Pré-requisitos

- Shopware 6.5, 6.6 ou 6.7 (`shopware/core` ~6.5 || ~6.6 || ~6.7)
- Acesso à linha de comandos para limpar a cache e instalar os recursos
- Sem dependências externas, sem serviços de terceiros

## Instalação

1. Na administração, vá a **Extensões → As minhas extensões → Carregar extensão** e selecione o ZIP.
2. Instale e depois **ative** a extensão.
3. Limpe a cache e instale os recursos:

```
bin/console plugin:refresh
bin/console plugin:install --activate DffNotificationCenter
bin/console assets:install
bin/console cache:clear
```

Depois de instalar ou atualizar, limpe também a cache do navegador (Ctrl+F5) na página de administração para recarregar o módulo.

### Shopware 6.7 (administração Vite)

O módulo de administração é entregue **pré-compilado** com um ficheiro `entrypoints.json` do Vite. Carrega tal como está na 6.5, 6.6 e 6.7 sem passo de build. Basta executar, após cada atualização:

```
bin/console assets:install
bin/console cache:clear
```

## Configuração

Vá a **Extensões → As minhas extensões → Centro de Notificações → Configuração**. As definições podem ter âmbito por canal de venda.

### Sino de notificações

- **Ativar o sino** (predefinição: sim): mostra ou oculta o sino no storefront.
- **Número máximo de notificações apresentadas** (predefinição: 10): limitado entre 1 e 50 do lado do servidor.
- **Atualização em segundo plano** (predefinição: 60 s): intervalo de sondagem, `0` para desativar.
- **Som** (predefinição: não): toca um som ao receber uma notificação.
- **Animação** (predefinição: sim): anima o sino quando há notificações por ler.

### Notificações de produto automáticas

- **Criar uma notificação para cada novo produto** (predefinição: sim).
- **Apenas para produtos ativos** (predefinição: sim).
- **Expiração automática** (predefinição: 30 dias, `0` = nunca): a partir daí, a notificação de produto deixa de ser difundida.

### Notificações promocionais automáticas

- **Criar uma notificação na criação de uma promoção com código** (predefinição: **não**, a ativar explicitamente).

A notificação promocional é criada assim que uma promoção **ativa** tem um **código global**. Por conceção, os códigos individuais nunca são difundidos.

## Gerir as notificações na administração

O módulo de gestão encontra-se em **Marketing → Centro de Notificações**. Aí cria, agenda, segmenta e prioriza os seus anúncios, e consulta os KPI de visualizações e cliques.

Estão disponíveis três tipos:

- **Anúncio** (`manual`): título, mensagem, etiqueta do botão e ligação livres.
- **Produto** (`product`): ligada a um produto; a imagem de capa e a ligação para a página são resolvidas em tempo real a cada apresentação, nunca há ligações partidas.
- **Código promocional** (`promo`): apresenta um código com um botão «Copiar» do lado do cliente.

### Agendamento, segmentação e prioridade

- **Agendamento**: datas `validFrom` / `validUntil`; uma notificação fora da sua janela não é difundida.
- **Segmentação por grupo de clientes**: limita a difusão a um grupo de clientes (vazio = todos).
- **Segmentação por canal de venda**: limita a um canal (vazio = todos), útil em multiloja.
- **Prioridade**: inteiro; as prioridades mais elevadas aparecem primeiro, depois ordenação por data de criação decrescente.

## Funcionamento do lado do cliente

O sino insere-se no cabeçalho através de uma extensão Twig (`sw_extends`). Se o seu tema personalizar muito o cabeçalho, uma _alternativa_ em JavaScript insere automaticamente o sino ao lado do carrinho.

O painel obtém as notificações através de uma chamada AJAX. O selo mostra o número de não lidas, com som e animação opcionais e uma atualização em segundo plano configurável. A interface é acessível: atributos ARIA, navegação por teclado e apresentação em _bottom-sheet_ no telemóvel.

**Estado de leitura:** para os clientes com sessão iniciada, é registado do lado do servidor (tabela `dff_notification_read`) e portanto sincronizado entre dispositivos. Para os visitantes, fica no `localStorage` do navegador, e não é recolhido qualquer dado pessoal.

## Arquitetura técnica

A extensão segue as convenções do Shopware: entidades declaradas através da Data Abstraction Layer (DAL), controlador de storefront que devolve JSON, subscribers de eventos e migração SQL. Sem overrides: os templates são estendidos com `sw_extends`, o código é 100 % nativo.

### Entidades e Data Abstraction Layer

A entidade principal `dff_notification` (`NotificationDefinition`) tem os campos: `type`, `active`, `priority`, `validFrom`, `validUntil`, `customerGroupId`, `salesChannelId`, `productId` (e `productVersionId`), `promotionId`, `promoCode`, `views` e `clicks`. Os campos traduzíveis `title`, `message`, `buttonLabel` e `linkUrl` pertencem à entidade de tradução `dff_notification_translation`.

Associações: `ManyToOne` para `customer_group`, `sales_channel`, `product` e `promotion`; `OneToMany` para `dff_notification_read` (estado de leitura por cliente). As definições são registadas com a tag `shopware.entity.definition` e expostas à API (`ApiAware`).

### Esquema da base de dados

A migração `Migration1781049600NotificationCenter` cria três tabelas:

- `dff_notification`: a notificação, com índices em `active` e em `(product_id, product_version_id)`. Chaves estrangeiras para `customer_group` e `sales_channel` (`ON DELETE SET NULL`) e para `product` (`ON DELETE CASCADE`).
- `dff_notification_translation`: traduções por idioma (`title`, `message`, `button_label`, `link_url`).
- `dff_notification_read`: pares notificação/cliente, com índice único em `(dff_notification_id, customer_id)` para evitar leituras duplicadas.

### Rotas AJAX do storefront

As rotas são declaradas em XML (`Resources/config/routes.xml`) para se manterem compatíveis do Shopware 6.5 ao 6.7 (Symfony 6.x e 7.x). O controlador estende `AbstractController`, e não `StorefrontController`, porque apenas devolve JSON e o `setTwig()` desapareceu na 6.7.

- `GET /dff-nc/list` → `list()`: devolve as notificações difundíveis e incrementa as suas visualizações.
- `POST /dff-nc/read` → `markRead()`: marca como lida do lado do servidor (clientes com sessão iniciada); para os visitantes, a resposta indica um armazenamento `client`.
- `POST /dff-nc/click/{id}` → `click()`: incrementa o contador de cliques.

### Lógica de difusão (controlador list)

A consulta DAL filtra as notificações `active = true`, dentro da sua janela de validade (`validFrom` ≤ agora ≤ `validUntil`, limites nulos admitidos), correspondentes ao canal de venda atual (ou nulo) e ao grupo de clientes atual (ou nulo), ordenadas por prioridade e depois por data decrescente. Os produtos ligados são então resolvidos dinamicamente (associação `cover.media`): uma notificação de produto cujo produto tenha sido eliminado ou esteja indisponível no canal é ocultada silenciosamente. As visualizações das notificações efetivamente entregues são incrementadas numa única consulta.

### Notificações automáticas (subscribers)

O **ProductSubscriber** escuta `product.written`. A cada _insert_ de produto na versão _live_ (as variantes com `parentId` são ignoradas), e se a opção estiver ativa, cria uma notificação do tipo `product`, respeitando o filtro «apenas produtos ativos», a duração configurada (`validUntil`) e um controlo antiduplicados por produto.

O **PromotionSubscriber** escuta `promotion.written`. Como a administração cria primeiro a promoção e só depois preenche o código e a ativação por atualizações sucessivas, reage tanto aos _inserts_ como aos _updates_. Uma notificação `promo` só é criada se a promoção estiver **ativa** e tiver um **código global**, com transposição das datas `validFrom`/`validUntil` da promoção e controlo antiduplicados por promoção.

### Internacionalização

São entregues três idiomas para o storefront e a administração: francês, inglês e alemão (snippets `fr-FR`, `en-GB`, `de-DE`). Os títulos e mensagens predefinidos das notificações de produto e promocionais são gerados através do serviço de tradução (chaves `dffNc.*`).

## Privacidade (RGPD)

A extensão não recolhe qualquer dado pessoal. O estado de leitura dos visitantes fica no navegador deles (`localStorage`); o dos clientes com sessão iniciada é guardado do lado do servidor e associado à conta. Os contadores de visualizações e cliques são agregados ao nível da notificação, sem perfil individual.

## Desinstalação

Na desinstalação, as tabelas `dff_notification_read`, `dff_notification_translation` e `dff_notification` são eliminadas, **exceto** se a opção «conservar os dados do utilizador» estiver marcada, caso em que ficam intactas.

## Resolução de problemas

- **O sino não aparece**: verifique que o sino está ativo na configuração, execute de novo `assets:install` e `cache:clear`, e limpe a cache do navegador. A alternativa em JS insere-se ao lado do carrinho se o tema sobrepuser o cabeçalho.
- **Nenhuma notificação de produto criada**: a opção tem de estar ativa, o produto tem de ser um produto raiz (não uma variante) e, se o filtro estiver ativo, tem de estar marcado como ativo.
- **Nenhuma notificação promocional criada**: a opção vem desativada por predefinição; a promoção tem de estar ativa e ter um código global (os códigos individuais não são difundidos).
- **Módulo de administração não carregado na 6.7**: execute de novo `assets:install` e `cache:clear` e force o recarregamento do navegador (Ctrl+F5).