Barra di spedizione gratuita (dffreeshipbar) — Guida completa

Guida completa al modulo dffreeshipbar per PrestaShop 8 e 9: installazione, soglie per paese e per stato, filtro per corriere, posizioni di visualizzazione, multinegozio e risoluzione dei problemi. Tutte le regole di risoluzione sono documentate, casi limite inclusi.

Panoramica

dffreeshipbar mostra una barra di avanzamento che indica al cliente quanto gli manca da spendere per ottenere la spedizione gratuita. Al raggiungimento della soglia il messaggio passa a una conferma.

Il modulo lavora con le proprie soglie, salvate in tabelle dedicate. Non consulta mai la variabile nativa PS_SHIPPING_FREE_PRICE: puoi lasciarla a 0 e gestire la spedizione gratuita tramite le fasce del corriere senza alcun conflitto.

La particolarità del modulo è la sua risoluzione territoriale a due livelli. Una soglia può essere definita a livello di paese, ma anche a livello di stato PrestaShop — il che permette di trattare in modo diverso territori collegati amministrativamente allo stesso paese, come i dipartimenti d’oltremare legati alla Francia metropolitana.

Requisiti

• PrestaShop dalla 8.0 alla 9.x
• PHP 7.4 minimo (8.0 – 8.3 supportate)
• Tema Classic, Hummingbird o qualsiasi tema personalizzato che richiami gli hook standard
• Accesso amministratore al back office

Installazione

1. Nel back office, andare in Moduli → Gestore moduli → Carica un modulo.
2. Caricare il file dffreeshipbar-2.1.0.zip.
3. Cliccare su Installa e poi su Configura.

All’installazione il modulo crea due tabelle e registra i suoi hook:

• PREFIX_dffreeshipbar_country — soglie a livello di paese, con una colonna id_shop.
• PREFIX_dffreeshipbar_state — soglie a livello di stato, con una colonna id_shop.

Hook registrati: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Impostazioni generali

La schermata di configurazione si trova in Moduli → DataFirefly – Barra di spedizione gratuita → Configura. È composta da tre pannelli: impostazioni generali, regole corriere e soglie per territorio.

Soglia globale di ripiego

Due impostazioni collegate:

• Usa una soglia globale predefinita: su No, la barra compare solo nei territori configurati esplicitamente. Su Sì, ogni territorio non configurato riceve l’importo indicato sotto.
• Soglia globale predefinita: l’importo applicato come ultima istanza.

Lascia il ripiego disattivato se la spedizione gratuita copre solo poche destinazioni. Attivalo se è universale e le eccezioni sono rare.

Base di calcolo

• Confronta i totali IVA inclusa: determina se il totale del carrello viene valutato con o senza imposte. Deve corrispondere alla base usata dalle fasce del corriere, altrimenti la barra e il checkout non coincideranno.
• Includi le regole del carrello nel totale: se attivo, gli sconti vengono detratti prima del confronto con la soglia. Un carrello da 70 € con un buono da 10 € viene quindi valutato a 60 €.

Il totale valutato corrisponde a una chiamata nativa:

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Spese di spedizione e confezione regalo non contano mai ai fini dell’avanzamento.

Richiedi un indirizzo di consegna

Finché il cliente non inserisce un indirizzo, la destinazione è solo una stima e lo stato resta sconosciuto. Tre modalità:

• Mai: la barra compare già durante la navigazione del catalogo, in base al paese stimato.
• Per i paesi con stati (consigliata): la barra resta visibile ovunque tranne nei paesi i cui stati possono avere condizioni diverse. Un visitatore stimato in Belgio vede la barra; uno stimato in Francia la vede solo dopo aver inserito un indirizzo, poiché sarà il suo stato a determinare la soglia reale.
• Sempre: nulla finché non esiste un indirizzo sul carrello.

Posizioni e aspetto

• Mostra in cima alla pagina: banner visibile su tutto il sito.
• Mostra nel carrello e al checkout: blocco visualizzato nel momento della decisione.
• Attiva l’animazione: righe animate durante l’avanzamento. L’animazione viene automaticamente disattivata per i visitatori che impostano prefers-reduced-motion.
• Quattro colori: sfondo, barra, testo e messaggio di successo.

Per un posizionamento libero nel tema, il modulo implementa WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Soglie per territorio

È il cuore del modulo. La tabella elenca tutti i paesi attivi del negozio e, sotto ogni paese dotato di stati, i suoi stati rientrati.

Ordine di risoluzione

Per un dato indirizzo di consegna il modulo cerca in quest’ordine e si ferma alla prima corrispondenza:

1. Lo stato dell’indirizzo, se esiste una regola.
2. Il paese dell’indirizzo, se esiste una regola.
3. La soglia globale di ripiego, se attivata.

Se nessuno di questi tre passaggi produce un importo, la barra non viene mostrata.

Casella e campo importo: due effetti diversi

È il punto più importante della configurazione, e il più frainteso:

• Casella deselezionata → la barra è nascosta per quel territorio. Non eredita né dal paese padre né dalla soglia globale. La risoluzione si ferma lì.
• Casella selezionata, importo vuoto → la regola viene eliminata e il territorio eredita dal livello superiore.
• Casella selezionata, importo indicato → si applica quell’importo.

Esempio: solo territorio metropolitano

Caso comune di un negozio francese che offre la spedizione gratuita a 65 € in Francia metropolitana e in Corsica, ma non oltremare:

• Francia: casella selezionata, importo 65.
• Corsica: casella selezionata, importo vuoto — eredita i 65 € della Francia.
• Guadalupa, Martinica, Guyana francese, Riunione, Mayotte: caselle deselezionate. Nessuna barra su queste destinazioni.
• Soglia globale di ripiego: disattivata, così nessun altro paese riceve una barra per errore.

Un cliente in Guadalupa non vedrà mai la promessa di spedizione gratuita, benché il suo indirizzo appartenga al paese «Francia» in PrestaShop.

Filtro e ricerca

Il campo di ricerca filtra paesi e stati per nome. La casella Mostra solo i territori configurati riduce la tabella alle righe che hanno già una regola — utile in un negozio aperto a cento paesi.

I due pulsanti di salvataggio sono indipendenti: Salva paesi e Salva stati.

Regole corriere

Se la spedizione gratuita è concessa solo da alcuni corrieri, limita la visualizzazione di conseguenza. Tre modalità:

• Tutti i corrieri: nessun filtro.
• Mostra solo per i corrieri selezionati di seguito: lista bianca.
• Nascondi per i corrieri selezionati di seguito: lista nera.

Prima della scelta del corriere

Il corriere è noto solo alla fase di consegna. L’impostazione Prima della scelta del corriere decide cosa accade prima di quel momento:

• Mostra: la barra compare nel catalogo e nel carrello, poi scompare se il cliente sceglie un corriere escluso.
• Nascondi: la barra compare solo dopo la selezione di un corriere idoneo.

Aggiornamento in tempo reale

La barra viene ricalcolata lato server e aggiornata senza ricaricare la pagina a ogni evento del carrello: aggiunta, rimozione, cambio quantità, modifica indirizzo, cambio di fase del checkout.

Lo script è in ascolto sugli eventi PrestaShop updatedCart, updateCart, updatedAddressForm, changedCheckoutStep e updateDeliveryForm. Puoi forzare un aggiornamento manuale dal tuo codice:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

È il server a decidere la visibilità: se il territorio o il corriere non sono più idonei, la barra viene rimossa dal DOM invece di restare con un valore obsoleto.

Multinegozio

Le soglie sono salvate con una colonna id_shop. Ogni negozio ha quindi le proprie regole di paese e stato, indipendenti tra loro.

Per configurare un negozio specifico, seleziona il suo contesto in alto nel back office prima di aprire la schermata di configurazione. Il pannello delle soglie mostra il nome del negozio corrente come promemoria.

Traduzioni

Il modulo è fornito tradotto in italiano, francese, inglese, tedesco, spagnolo e polacco.

Per adattare i testi rivolti al cliente, andare in Internazionale → Traduzioni, selezionare «Traduzioni dei moduli», scegliere dffreeshipbar e la lingua, quindi cercare il dominio Modules.Dffreeshipbar.Shop. Stringhe disponibili:

• «Ti mancano solo %amount% per la spedizione gratuita!» — carrello in corso.
• «Spedizione gratuita a partire da %amount%.» — carrello vuoto.
• «Complimenti! Il tuo ordine beneficia della spedizione gratuita.» — soglia raggiunta.

Il segnaposto %amount% viene sostituito con l’importo formattato secondo la valuta e la localizzazione attive. Conservalo nelle tue traduzioni.

Aggiornamento dalla versione 1.0

L’aggiornamento è automatico alla sostituzione dello ZIP. Gli script di upgrade eseguono le operazioni seguenti:

• Creazione della tabella degli stati.
• Rinomina della colonna active in enabled nella tabella dei paesi. Le soglie esistenti sono conservate.
• La soglia globale di ripiego viene attivata se ne avevi una nella 1.0, per non modificare ciò che vedono i tuoi clienti.
• La modalità di obbligo indirizzo viene impostata su Mai, che corrisponde al comportamento della 1.0. Passa alla modalità consigliata quando lo ritieni opportuno.

Risoluzione dei problemi

La barra non compare da nessuna parte

1. Il modulo è attivo? (interruttore Attiva il modulo).
2. Hai configurato almeno un territorio o attivato la soglia globale di ripiego? Senza l’uno o l’altra, la barra non compare mai.
3. La modalità di obbligo indirizzo è su Sempre mentre provi senza indirizzo di consegna?
4. Le posizioni sono attive? (banner e/o carrello).
5. Il tuo tema richiama gli hook utilizzati? Verificare in Moduli → Posizioni. Con un tema personalizzato, usare piuttosto il widget.

La barra compare dove non dovrebbe

Il caso tipico è un territorio che eredita quando dovrebbe essere escluso. Verifica che la casella del territorio sia davvero deselezionata, e non semplicemente che ne sia stato svuotato l’importo — le due azioni hanno effetti opposti.

La soglia mostrata non corrisponde al checkout

• Verifica che Confronta i totali IVA inclusa corrisponda alla base delle fasce del corriere.
• Verifica l’impostazione sulle regole del carrello: un carrello scontato può scendere sotto la soglia.
• Il modulo non legge le fasce del corriere. Se hai modificato una fascia, riporta il nuovo valore nel modulo.

La barra non si aggiorna dopo un’aggiunta al carrello

L’aggiornamento si basa sugli eventi JavaScript di PrestaShop. Alcuni temi o moduli carrello di terze parti non li emettono. Due verifiche:

• La console del browser segnala un errore JavaScript su un’altra risorsa? Un errore bloccante a monte impedisce l’installazione del listener.
• Il tuo modulo carrello ajax emette davvero prestashop.emit('updatedCart')? In caso contrario, lancia dffreeshipbar:refresh dal tuo codice.

Le regole corriere sembrano ignorate

Verifica che il corriere selezionato sia quello che credi: dopo una variazione di tariffa PrestaShop ne crea uno nuovo. Il modulo segue il riferimento, quindi la regola dovrebbe seguirlo — ma se il corriere è stato ricreato da zero anziché modificato, il suo riferimento è nuovo e va riselezionato.

Disinstallazione

Andare in Moduli → Gestore moduli → DataFirefly – Barra di spedizione gratuita → Disinstalla. La disinstallazione elimina entrambe le tabelle delle soglie e tutte le chiavi di configurazione con prefisso DFFREESHIPBAR_.

FAQ rapida

• Il modulo legge PS_SHIPPING_FREE_PRICE? Mai. Puoi lasciarla a 0 e gestire la spedizione gratuita con le fasce del corriere.
• Il modulo legge le mie fasce corriere per dedurne la soglia? No. Le soglie si inseriscono manualmente. Una sincronizzazione automatica dalle fasce è possibile come sviluppo su misura.
• La mia spedizione gratuita dipende anche dal peso. È gestita? No, il modulo misura solo un importo. Una condizione di peso è uno sviluppo su misura.
• Posso mostrare la barra fuori dalle posizioni proposte? Sì, tramite {widget name='dffreeshipbar'} in qualsiasi template.
• Il modulo funziona con il tema Hummingbird? Sì. Gli hook displayNavFullWidth e displayCheckoutSummaryTop sono registrati per esso, e il widget copre i posizionamenti personalizzati.
• Le soglie sono indipendenti per negozio? Sì, ogni riga porta un id_shop.

Supporto e aggiornamenti

Il modulo include 12 mesi di aggiornamenti e supporto dalla data di acquisto. Supporto via email in francese o inglese, risposta entro 24 ore lavorative.

Per qualsiasi domanda o anomalia, contattare il supporto DataFirefly indicando:

• Versione di PrestaShop e di PHP
• Versione del modulo installata
• Tema utilizzato
• Territorio e corriere coinvolti nel comportamento osservato
• Comportamento osservato rispetto a quello atteso