Contatore Carrelli per Shopware 6: installazione e configurazione

Il plugin DfCartPopularity mostra sulla scheda prodotto un badge con il numero di carrelli che contengono attualmente il prodotto, ad esempio «In più di 20 carrelli». Il conteggio si basa sui vostri dati reali di carrello.

Prerequisiti

• Shopware 6.5, 6.6 o 6.7 in installazione self hosted (il SaaS Shopware Cloud non accetta plugin server)
• PHP 8.1 o superiore
• Accesso SSH per i comandi da console e la compilazione del tema

Installazione

Caricate lo ZIP da Estensioni e poi Le mie estensioni, oppure copiate la cartella in custom/plugins/, quindi eseguite:

bin/console plugin:refresh
bin/console plugin:install --activate DfCartPopularity
bin/console cache:clear
./bin/build-storefront.sh

La compilazione dello storefront è necessaria una volta, per includere il foglio di stile del badge. In un ambiente gestito da una pipeline di deploy questo passaggio fa di solito già parte del processo standard.

Inizializzare l’indice

Dopo l’installazione l’indice è vuoto: i contatori partono da zero e si riempiono man mano che i clienti modificano il carrello. Per mostrare cifre credibili fin dal primo giorno, lanciate la ricostruzione:

bin/console df:cart-popularity:rebuild

Il comando legge i carrelli già presenti nel negozio e alimenta l’indice. È idempotente e può essere rilanciato senza rischi. L’opzione --truncate svuota l’indice prima della ricostruzione.

Configurazione

Impostazioni, Sistema, Plugin, DataFirefly Cart Popularity, quindi Configura. Ogni opzione è sovrascrivibile canale di vendita per canale di vendita.

Visualizzazione

• Attivare il badge: il tracciamento dei carrelli continua anche a badge disattivato, così i dati sono pronti il giorno in cui lo attivate.
• Soglia minima (predefinito 5): sotto questo numero di carrelli non viene mostrato nulla.
• Modalità di visualizzazione: fascia arrotondata o numero esatto.
• Passo della fascia (predefinito 10): un conteggio di 23 viene mostrato come «più di 20». Se il conteggio è inferiore al passo, il plugin passa automaticamente al numero esatto invece di annunciare una fascia falsa.
• Posizione: sopra o sotto il blocco di acquisto.
• Stile del badge: sfondo tenue, contorno o solo testo.

Regole di conteggio

• Finestra temporale (predefinito 7 giorni): vengono contati solo i carrelli aggiornati entro questa finestra. Il valore 0 la disattiva.
• Solo carrelli attivi: esclude i carrelli già trasformati in ordine.
• Limitare al canale di vendita: evita che un picco su un negozio gonfi il contatore di un altro.
• Aggregare le varianti: tutte le varianti di un prodotto condividono il contatore del padre. Disattivate l’opzione se ogni variante deve avere il proprio contatore.

Prestazioni e conservazione

• Durata della cache (predefinito 900 secondi): la query di conteggio viene eseguita una volta per durata e per prodotto. Il valore 0 disattiva la cache. La cache viene svuotata automaticamente al salvataggio della configurazione.
• Conservazione (predefinito 60 giorni): i record più vecchi vengono eliminati. La pulizia viene eseguita automaticamente, al massimo una volta all’ora, senza dipendere dalla coda di messaggi.

Personalizzare il testo

Il testo del badge risiede negli snippet di Shopware. Impostazioni, Snippet, quindi cercate dfCartPopularity. Sono disponibili tre chiavi:

• dfCartPopularity.badge.textTier: modalità fascia, contiene il segnaposto del numero
• dfCartPopularity.badge.textExact: modalità esatta, contiene il segnaposto del numero
• dfCartPopularity.badge.textSingular: modalità esatta con un solo carrello

Il segnaposto si scrive %count% e va mantenuto nella vostra formulazione. Sono fornite le traduzioni in inglese, tedesco, francese, spagnolo, italiano e polacco.

Come funziona il conteggio

Shopware serializza l’intero carrello in una colonna payload della tabella cart, spesso compressa. Nessuna query SQL può quindi sapere cosa contiene un carrello senza deserializzarlo. Il plugin mantiene una propria tabella df_cart_popularity che associa token del carrello, prodotto, canale di vendita, quantità e indicatore di ordine.

Questa tabella viene sincronizzata a ogni persistenza del carrello tramite CartSavedEvent, con due query indicizzate. L’evento CartConvertedEvent contrassegna le righe come ordinate al momento dell’ordine. La visualizzazione esegue poi un semplice conteggio distinto su un indice composito, mantenuto in cache.

Comandi CLI

bin/console df:cart-popularity:rebuild
bin/console df:cart-popularity:rebuild --truncate
bin/console df:cart-popularity:cleanup
bin/console df:cart-popularity:cleanup --days=30

Risoluzione dei problemi

Il badge non compare

Verificate nell’ordine: il badge è attivo per quel canale di vendita, il numero di carrelli raggiunge la soglia, la finestra temporale non esclude tutti i carrelli e lo storefront è stato ricompilato dopo l’installazione. Svuotate anche la cache HTTP se la pagina viene servita dalla cache.

Il badge compare senza stile

Il foglio di stile del plugin viene incluso nella compilazione del tema. Rilanciate ./bin/build-storefront.sh oppure bin/console theme:compile.

Il comando di ricostruzione segnala carrelli ignorati

Quei carrelli usano un formato di payload che il comando non sa leggere, tipicamente uno storage di carrello esternalizzato. Saranno indicizzati normalmente alla successiva modifica del cliente, poiché il tracciamento a eventi funziona indipendentemente dalla modalità di storage.

Disinstallazione

La disinstallazione con rimozione dei dati utente elimina la tabella df_cart_popularity e la configurazione del plugin. Conservando i dati utente la tabella resta e i contatori riprendono invariati in caso di reinstallazione.