Contatore di Vendite Shopware 6: guida a installazione e configurazione

Questa guida copre l’installazione, la configurazione e la personalizzazione del plugin DfSalesCounter, che mostra su ogni scheda prodotto quante volte un prodotto è già stato venduto, a partire dagli ordini reali del tuo negozio Shopware 6.

Prerequisiti

• Shopware 6.5.x, 6.6.x o 6.7.x in installazione self-hosted. Shopware Cloud (SaaS) non accetta plugin server.
• PHP 8.1 o superiore.
• Un tema storefront derivato dal tema Storefront di Shopware, oppure un tema personalizzato che conservi i blocchi Twig standard del blocco d’acquisto.
• L’accesso da riga di comando è consigliato per la compilazione del tema, ma anche l’installazione dall’amministrazione funziona.

Installazione

Caricamento dello ZIP dall’amministrazione

1. Nell’amministrazione Shopware apri Estensioni, poi Le mie estensioni.
2. Clicca su Carica estensione e seleziona il file DfSalesCounter-1.0.0.zip.
3. Quando il plugin compare nell’elenco, clicca su Installa e attivalo con l’interruttore.
4. Ricompila il tema da Contenuti, Temi, selezionando il tuo tema e poi Ricompila tema. Questo passaggio serve una sola volta, perché il plugin include un foglio di stile storefront.

Da riga di comando

Posiziona la cartella DfSalesCounter in custom/plugins/ della tua installazione, poi esegui:

bin/console plugin:refresh
bin/console plugin:install --activate DfSalesCounter
bin/console theme:compile
bin/console cache:clear

In un ambiente con una pipeline di deploy, la compilazione del tema fa di solito già parte dei passaggi standard.

Configurazione

La pagina di configurazione si trova in Estensioni, Le mie estensioni, pulsante … a destra di DataFirefly Sales Counter, poi Configura. Il selettore in cima alla pagina permette di scegliere il canale di vendita a cui si applica la configurazione: ogni canale può avere la propria soglia, il proprio testo e la propria posizione.

Scheda Generale

• Attiva il contatore di vendite: interruttore principale. Disattivato, nessuna query viene eseguita e nessun badge viene renderizzato.
• Modalità di conteggio: Quantità venduta somma tutte le quantità ordinate del prodotto. Numero di ordini conta gli ordini distinti che hanno incluso il prodotto. La prima modalità valorizza il volume, la seconda il numero di clienti diversi convinti.
• Ordini considerati: Tutti gli ordini restituisce il dato grezzo. Escludi gli ordini annullati scarta quelli il cui stato macchina è cancelled. Solo ordini pagati conserva soltanto gli ordini con una transazione in stato paid o paid_partially.
• Soglia minima prima della visualizzazione: al di sotto di questo valore non compare alcun badge. Il valore predefinito è 5. Una soglia di 0 viene trattata come 1, il badge non viene mai renderizzato su un prodotto senza vendite.
• Periodo in giorni: limita il conteggio agli ultimi X giorni, in base alla data dell’ordine. Il valore 0 indica un totale complessivo.
• Somma le vendite di tutte le varianti: aggiunge le vendite del prodotto padre e di tutte le sue varianti. Consigliato su un catalogo moda o a taglie, da disattivare quando ogni variante corrisponde a un impiego distinto.
• Conta solo gli ordini del canale di vendita corrente: evita che un negozio B2B o un canale export gonfi i numeri mostrati sul negozio al pubblico.

Scheda Visualizzazione

• Posizione sulla scheda prodotto: Sotto il nome del prodotto, Sotto il prezzo, oppure Sotto il blocco d’acquisto, cioè in fondo al blocco, sotto il pulsante di aggiunta al carrello.
• Stile visivo: Badge rende una pillola bordata, Testo semplice rende una riga senza cornice, Banda rende un blocco a tutta larghezza con una barra laterale colorata.
• Icona: fiamma, carrello, spunta o nessuna. Le icone sono SVG inline, non viene caricato alcun font di icone.
• Colore d’accento: lasciato vuoto, viene usato il colore primario del tema. Se compilato, alimenta la variabile CSS --df-sales-counter-accent sull’elemento del badge.
• Separatore delle migliaia: spazio stretto, virgola, punto o nessuno. Utile non appena i contatori superano il migliaio.
• Testo personalizzato: vedi la sezione successiva.
• Durata della cache in secondi: 900 per impostazione predefinita. Il valore 0 disattiva la cache e interroga il database a ogni visualizzazione della scheda.

Personalizzare il testo

Testo globale dalla configurazione

Il campo Testo personalizzato accetta una frase con il segnaposto %count% nel punto in cui deve comparire il numero. Esempio: Questo modello è uscito %count% volte questo mese. Quel testo è comune a tutte le lingue del canale di vendita. Viene sanificato prima del rendering, il che consente un markup semplice come <strong> ma blocca qualsiasi script.

Testi per lingua tramite gli snippet

Lascia vuoto il campo Testo personalizzato per gestire il testo lingua per lingua. Apri Impostazioni, Negozio, Snippet, poi cerca dfSalesCounter. Sono disponibili quattro chiavi:

• dfSalesCounter.badge.quantitySingular e dfSalesCounter.badge.quantityPlural, usate in modalità quantità venduta.
• dfSalesCounter.badge.ordersSingular e dfSalesCounter.badge.ordersPlural, usate in modalità numero di ordini.

Ogni valore accetta il segnaposto %count%. Le traduzioni italiana, inglese, francese, spagnola e tedesca sono incluse nel plugin. Un valore modificato nel gestore degli snippet ha la precedenza su quello del plugin, anche dopo un aggiornamento.

Come viene calcolato il numero

Il plugin legge le righe d’ordine di tipo prodotto, unite all’ordine e al suo stato. Il calcolo avviene con una sola query aggregata, senza processi in background e senza tabella dedicata.

• In modalità quantità, la query somma la colonna delle quantità delle righe d’ordine.
• In modalità ordini, conta gli identificatori d’ordine distinti.
• Viene considerata solo la versione attiva degli ordini, le versioni di lavoro create durante una nota di credito o una modifica d’ordine vengono ignorate.
• Con la somma delle varianti attiva, il plugin risolve prima la famiglia del prodotto mostrato, prodotto padre e varianti, poi filtra sull’insieme degli identificatori.

Se il risultato è inferiore alla soglia configurata, nessuna estensione viene aggiunta al prodotto e il template non rende nulla. Il badge quindi non esiste nell’HTML, il che evita qualsiasi visualizzazione residua tramite una regola CSS del tema.

Cache e freschezza del dato

Il risultato viene memorizzato nel pool di cache applicativa di Symfony, sotto una chiave che combina l’identificatore del prodotto, il canale di vendita e una firma delle opzioni che influenzano il calcolo. Modificare la modalità di conteggio, l’ambito degli ordini, il periodo o le opzioni di somma cambia quella firma e invalida quindi automaticamente i valori precedenti.

A ogni ordine effettuato, il plugin svuota la cache dei prodotti contenuti in quell’ordine, oltre a quella del loro prodotto padre. Il contatore riflette dunque la vendita senza attendere la scadenza della durata configurata.

Su un catalogo di dimensioni modeste la durata della cache può essere portata a 0 senza conseguenze rilevanti: la query lavora su colonne indicizzate. Su un catalogo ampio con traffico elevato, mantieni una durata di alcuni minuti.

Personalizzazione avanzata del rendering

Il plugin sovrascrive il blocco d’acquisto della pagina prodotto e inserisce il badge in tre blocchi Twig standard, a seconda della posizione scelta: il blocco del nome prodotto, il blocco del contenitore del prezzo e il blocco del contenitore d’acquisto. Il badge stesso è renderizzato da un template di componente dedicato, storefront/component/df-sales-counter/badge.html.twig, che espone due blocchi sovrascrivibili, uno per l’icona e uno per il testo.

Da un tema o da un plugin, l’estensione è accessibile in Twig sul prodotto della pagina con il nome dfSalesCounter. Espone il numero grezzo, il numero formattato, la posizione, lo stile, l’icona, il colore d’accento, il testo personalizzato e la modalità di conteggio. Puoi quindi rendere il contatore altrove rispetto al blocco d’acquisto, per esempio in una scheda di informazioni prodotto, recuperando l’estensione e includendo il componente.

Gli stili sono definiti in Resources/app/storefront/src/scss/base.scss attorno alle classi df-sales-counter, df-sales-counter__icon e df-sales-counter__text, con un modificatore per ciascuno stile visivo. Qualsiasi regola del tuo tema compilata dopo quella del plugin ha la precedenza, senza dover modificare il plugin.

Risoluzione dei problemi

Non compare alcun badge

Verifica nell’ordine: il plugin è attivato, l’interruttore di attivazione è su sì per il canale di vendita corretto, il prodotto ha raggiunto la soglia configurata, e l’ambito degli ordini scelto non esclude tutti i tuoi ordini. Una soglia di 5 con ambito Solo ordini pagati su un negozio di prova i cui ordini non vengono mai contrassegnati come pagati non produrrà mai alcuna visualizzazione.

Il badge compare senza stile

Il tema non è stato ricompilato dopo l’attivazione. Esegui bin/console theme:compile oppure usa il pulsante di ricompilazione nell’amministrazione.

Il numero sembra bloccato

La durata della cache non è ancora scaduta. Svuota la cache applicativa con bin/console cache:pool:clear cache.app, oppure porta temporaneamente la durata a 0 per validare il calcolo.

Il badge non compare nel punto giusto

Un tema molto personalizzato può aver rimosso o rinominato i blocchi Twig del blocco d’acquisto. Prova un’altra posizione nella configurazione, oppure includi il componente manualmente nel tuo template recuperando l’estensione del prodotto.

Aggiornamento e disinstallazione

Un aggiornamento si effettua caricando il nuovo ZIP e cliccando su Aggiorna, seguito da una ricompilazione del tema se la versione contiene modifiche di stile. La configurazione viene conservata.

Alla disinstallazione, una casella propone di conservare i dati utente. Deselezionata, tutte le chiavi di configurazione del plugin vengono rimosse. Il plugin non crea alcuna tabella e non esegue alcuna migrazione, quindi la disinstallazione non lascia nulla nel database oltre alla sua configurazione.

Riferimento delle chiavi di configurazione

Tutte le chiavi hanno il prefisso DfSalesCounter.config. e sono gestibili tramite Admin API o il comando system:config:set:

• active, booleano
• countMode, valori quantity oppure orders
• orderScope, valori all, notCancelled oppure paid
• minThreshold, intero
• periodDays, intero
• aggregateVariants, booleano
• scopeToSalesChannel, booleano
• position, valori afterName, afterPrice oppure afterBuy
• style, valori badge, inline oppure banner
• icon, valori none, flame, cart oppure check
• accentColor, stringa esadecimale
• thousandSeparator, valori space, comma, dot oppure none
• customText, stringa
• cacheTtl, intero in secondi