Centro Notifiche per Shopware 6 — Installazione, configurazione e documentazione tecnica

Panoramica

Il Centro Notifiche DataFirefly aggiunge una campanella delle notifiche all’header dello storefront di Shopware 6, proprio accanto al carrello. Un badge rosso indica il numero di messaggi non letti (mostrato come «9+» oltre i nove) e un pannello a discesa presenta i tuoi annunci, i nuovi prodotti e i codici promozionali.

Il plugin gestisce tre tipi di notifica: annunci redatti manualmente, notifiche prodotto create automaticamente per ogni nuovo prodotto (immagine e link risolti in tempo reale) e codici promozionali con un pulsante «Copia» in un clic. Ogni notifica può essere pianificata, targetizzata per gruppo clienti e canale di vendita, prioritizzata e misurata tramite KPI di visualizzazioni e clic.

Un solo plugin, un solo ZIP, compatibile con Shopware 6.5, 6.6 e 6.7 — inclusa l’amministrazione basata su Vite della 6.7, consegnata precompilata senza fase di build.

Requisiti

• Shopware 6.5, 6.6 o 6.7 (shopware/core ~6.5 || ~6.6 || ~6.7)
• Accesso alla riga di comando per svuotare la cache e installare gli asset
• Nessuna dipendenza esterna, nessun servizio di terze parti

Installazione

1. Nell’amministrazione, vai su Estensioni → Le mie estensioni → Carica estensione e seleziona lo ZIP.
2. Installa e poi attiva il plugin.
3. Svuota la cache e installa gli asset:

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

Shopware 6.7 (amministrazione Vite)

Il modulo di amministrazione viene consegnato precompilato con un file Vite entrypoints.json. Si carica così com’è su 6.5, 6.6 e 6.7 senza fase di build. Dopo ogni aggiornamento, esegui semplicemente:

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

Configurazione

Vai su Estensioni → Le mie estensioni → Centro Notifiche → Configura. Le impostazioni sono definibili per canale di vendita.

Campanella delle notifiche

• Attiva la campanella (predefinito: sì): mostra o nasconde la campanella nello storefront.
• Numero massimo di notifiche mostrate (predefinito: 10): limitato tra 1 e 50 lato server.
• Intervallo di aggiornamento in background (predefinito: 60 s): intervallo di polling, 0 per disattivare.
• Suono (predefinito: no): riproduce un suono all’arrivo di una notifica.
• Animazione (predefinito: sì): anima la campanella in presenza di notifiche non lette.

Notifiche prodotto automatiche

• Crea una notifica per ogni nuovo prodotto (predefinito: sì).
• Solo per prodotti attivi (predefinito: sì).
• Scadenza automatica (predefinito: 30 giorni, 0 = mai): oltre tale termine, la notifica prodotto non viene più mostrata.

Notifiche promo automatiche

• Crea una notifica alla creazione di una promozione con codice (predefinito: no, da attivare esplicitamente).

Gestire le notifiche nell’amministrazione

Il modulo di gestione si trova in Marketing → Centro Notifiche. Lì crei, pianifichi, targetizzi e prioritizzi i tuoi annunci e consulti i KPI visualizzazioni/clic.

Sono disponibili tre tipi:

• Annuncio (manual): titolo, messaggio, etichetta del pulsante e link liberi.
• Prodotto (product): collegata a un prodotto; l’immagine di copertina e il link alla scheda vengono risolti in tempo reale a ogni rendering — mai un link rotto.
• Codice promozionale (promo): mostra un codice con un pulsante «Copia» lato client.

Pianificazione, targeting e priorità

• Pianificazione: date validFrom / validUntil; una notifica fuori dalla sua finestra non viene diffusa.
• Targeting per gruppo clienti: limita la diffusione a un determinato gruppo clienti (vuoto = tutti).
• Targeting per canale di vendita: limita a un canale (vuoto = tutti), utile nelle configurazioni multi-negozio.
• Priorità: intero; le priorità più alte vengono mostrate per prime, poi ordinate per data di creazione decrescente.

Comportamento lato client

La campanella viene inserita nell’header tramite un’estensione Twig (sw_extends). Se il tuo tema personalizza fortemente l’header, un fallback JavaScript inserisce automaticamente la campanella accanto al carrello.

Il pannello recupera le notifiche tramite una chiamata AJAX. Il badge mostra il conteggio dei non letti, con suono e animazione opzionali e un aggiornamento in background configurabile. L’interfaccia è accessibile: attributi ARIA, navigazione da tastiera e layout a bottom-sheet su mobile.

Architettura tecnica

Il plugin segue le convenzioni di Shopware: entità dichiarate tramite la Data Abstraction Layer (DAL), un controller storefront che restituisce JSON, subscriber di eventi e una migrazione SQL. Nessun override — i template vengono estesi tramite sw_extends e il codice è 100% nativo.

Entità e Data Abstraction Layer

L’entità principale dff_notification (NotificationDefinition) porta i campi: type, active, priority, validFrom, validUntil, customerGroupId, salesChannelId, productId (+ productVersionId), promotionId, promoCode, views e clicks. I campi traducibili title, message, buttonLabel e linkUrl sono portati dall’entità di traduzione dff_notification_translation.

Associazioni: ManyToOne verso customer_group, sales_channel, product e promotion; OneToMany verso dff_notification_read (stato di lettura per cliente). Le definizioni sono registrate con il tag shopware.entity.definition ed esposte all’API (ApiAware).

Schema del database

La migrazione Migration1781049600NotificationCenter crea tre tabelle:

• dff_notification: la notifica, con indici su active e su (product_id, product_version_id). Chiavi esterne verso customer_group e sales_channel (ON DELETE SET NULL) e verso product (ON DELETE CASCADE).
• dff_notification_translation: traduzioni per lingua (title, message, button_label, link_url).
• dff_notification_read: coppie notifica/cliente, con un indice univoco su (dff_notification_id, customer_id) per evitare letture duplicate.

Route AJAX dello storefront

Le route sono dichiarate in XML (Resources/config/routes.xml) per restare compatibili da Shopware 6.5 a 6.7 (Symfony 6.x e 7.x). Il controller estende AbstractController — non StorefrontController — perché restituisce solo JSON e setTwig() è stato rimosso nella 6.7.

• GET /dff-nc/list → list(): restituisce le notifiche diffondibili e incrementa le loro visualizzazioni.
• POST /dff-nc/read → markRead(): segna come letto lato server (clienti registrati); per gli ospiti la risposta indica archiviazione client.
• POST /dff-nc/click/{id} → click(): incrementa il contatore dei clic.

Logica di diffusione (controller list)

La query DAL filtra le notifiche con active = true, entro la loro finestra di validità (validFrom ≤ ora ≤ validUntil, limiti nulli ammessi), corrispondenti al canale di vendita corrente (o nullo) e al gruppo clienti corrente (o nullo), ordinate per priorità e poi per data di creazione decrescente. I prodotti collegati vengono poi risolti dinamicamente (associazione cover.media): una notifica prodotto il cui prodotto è stato eliminato o non è disponibile nel canale viene nascosta silenziosamente. Le visualizzazioni delle notifiche effettivamente mostrate vengono incrementate in un’unica query.

Notifiche automatiche (subscriber)

ProductSubscriber ascolta product.written. A ogni insert di prodotto sulla versione live (le varianti con un parentId vengono ignorate), e se l’opzione è attiva, crea una notifica di tipo product — rispettando il filtro «solo prodotti attivi», la durata configurata (validUntil) e un controllo anti-duplicati per prodotto.

PromotionSubscriber ascolta promotion.written. Poiché l’amministrazione crea prima la promozione e poi ne imposta il codice e il flag di attivazione tramite aggiornamenti successivi, reagisce sia agli insert sia agli update. Una notifica promo viene creata solo se la promozione è attiva e possiede un codice globale, riportando le date validFrom/validUntil della promozione con un controllo anti-duplicati per promozione.

Internazionalizzazione

Vengono fornite tre lingue per storefront e amministrazione: francese, inglese e tedesco (snippet fr-FR, en-GB, de-DE). I titoli e i messaggi predefiniti delle notifiche prodotto e promo sono generati tramite il servizio di traduzione (chiavi dffNc.*).

Privacy (GDPR)

Il plugin non raccoglie alcun dato personale. Lo stato di lettura degli ospiti resta nel loro browser (localStorage); quello dei clienti registrati è memorizzato lato server e collegato al loro account. I contatori di visualizzazioni e clic sono aggregati a livello di notifica, senza profilazione individuale.

Disinstallazione

Alla disinstallazione, le tabelle dff_notification_read, dff_notification_translation e dff_notification vengono eliminate — a meno che l’opzione «conserva i dati utente» sia selezionata, nel qual caso restano intatte.

Risoluzione dei problemi

• La campanella non appare: verifica che la campanella sia attivata nella configurazione, riesegui assets:install e cache:clear, poi svuota la cache del browser. Il fallback JS la inserisce accanto al carrello se il tema sovrascrive l’header.
• Nessuna notifica prodotto creata: l’opzione deve essere attiva, il prodotto deve essere un prodotto radice (non una variante) e, se il filtro è attivo, contrassegnato come attivo.
• Nessuna notifica promo creata: l’opzione è disattivata per impostazione predefinita; la promozione deve essere attiva e avere un codice globale (i codici individuali non vengono diffusi).
• Il modulo di amministrazione non si carica su 6.7: riesegui assets:install poi cache:clear e forza un ricaricamento del browser (Ctrl+F5).