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

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

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.

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