# Barra di spedizione gratuita (dffreeshipbar): guida completa

> Guida completa al modulo dffreeshipbar 2.3.0 per PrestaShop 8 e 9: installazione, soglie per paese e per stato, posizioni di visualizzazione (comprese la scheda prodotto e il carrello laterale di…

- Pagina: <https://www.datafirefly.com/it/documentation/dffreeshipbar/>
- Lingua: it
- Aggiornato il: 2026-09-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dffreeshipbar/index.md), [en](https://www.datafirefly.com/en/documentation/dffreeshipbar/index.md), [es](https://www.datafirefly.com/es/documentation/dffreeshipbar/index.md), [de](https://www.datafirefly.com/de/documentation/dffreeshipbar/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreeshipbar/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreeshipbar/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreeshipbar/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

Guida completa al modulo **dffreeshipbar** 2.3.0 per PrestaShop 8 e 9: installazione, soglie per paese e per stato, posizioni di visualizzazione (comprese la scheda prodotto e il carrello laterale di Creative Elements), messaggi, aspetto, corrieri, multivaluta e risoluzione dei problemi.

## 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 con le fasce del corriere senza conflitti.

La sua particolarità è la **risoluzione territoriale a due livelli**: una soglia può essere definita per paese e per stato PrestaShop. Territori collegati allo stesso paese, come i dipartimenti d'oltremare legati alla Francia, possono così essere trattati diversamente.

## Requisiti

- PrestaShop dalla 8.0 alla 9.x
- PHP 7.4 minimo (8.0 - 8.3 supportate)
- Tema Classic, Hummingbird o un tema personalizzato che richiami gli hook standard
- Creative Elements (facoltativo) per la posizione nel carrello laterale

## Installazione

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

Il modulo crea due tabelle (`PREFIX_dffreeshipbar_country` e `PREFIX_dffreeshipbar_state`, ciascuna con una colonna `id_shop`) e registra gli hook `displayHeader`, `displayBanner`, `displayNav2`, `displayNavFullWidth`, `displayShoppingCartFooter`, `displayCheckoutSummaryTop`, `displayProductAdditionalInfo`, `displayCEShoppingCartFooter` e `actionCarrierUpdate`.

**Nota.** La soglia globale di ripiego è disattivata per impostazione predefinita. Finché nessun territorio ha una soglia, la barra non compare da nessuna parte, e la fascia di riepilogo del back office lo segnala. Meglio nessuna barra che una barra che promette una spedizione gratuita non offerta.

## La schermata di configurazione

La schermata si trova in **Moduli → DataFirefly - Barra di spedizione gratuita → Configura**. In alto, una fascia di riepilogo indica lo stato del modulo, il numero di territori con soglia e di territori esclusi, la soglia di ripiego, il filtro corrieri e le posizioni attive. Ogni riquadro apre la scheda corrispondente.

La configurazione è divisa in cinque schede: **Generale**, **Territori**, **Corrieri**, **Messaggi** e **Aspetto**. La scheda attiva resta selezionata dopo il salvataggio.

## Scheda Generale

### Soglia globale di ripiego

- **Usa una soglia globale predefinita**: su _No_, la barra compare solo nei territori configurati. Su _Sì_, ogni territorio non configurato riceve l'importo inserito.
- **Soglia globale predefinita**: l'importo applicato come ultima istanza.

### Multivaluta

Tutti gli importi del modulo si inseriscono nella **valuta predefinita** del negozio. Per un visitatore che paga in un'altra valuta, la soglia viene convertita al tasso di cambio di PrestaShop prima del confronto con il suo carrello, e gli importi visualizzati sono formattati nella sua valuta.

### Richiedi un indirizzo di consegna

Prima dell'inserimento di un indirizzo, la destinazione è solo una stima e lo stato resta sconosciuto. Tre modalità:

- **Mai**: la barra compare durante la navigazione, 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, dove attende l'indirizzo.
- **Sempre**: nulla finché non esiste un indirizzo sul carrello.

### Base di calcolo

- **Confronta i totali IVA inclusa**: deve corrispondere alla base delle fasce del corriere, altrimenti barra e checkout non coincidono.
- **Includi le regole del carrello nel totale**: un carrello da 70 € con un buono da 10 € viene allora valutato a 60 €.

Le spese di spedizione non contano mai ai fini dell'avanzamento.

### Gruppi di clienti

Senza caselle selezionate, tutti i clienti vedono la barra. Seleziona dei gruppi per riservarla a loro, ad esempio ai privati quando i professionisti hanno altre condizioni di spedizione. Un visitatore non connesso appartiene al gruppo «Visitatore».

### Nascondi finché il carrello è vuoto

La barra compare con il primo prodotto aggiunto. La scheda prodotto la mantiene in ogni caso, perché è lì che il cliente decide di aggiungere.

### Posizioni di visualizzazione

- **Cima della pagina**: banner visibile su tutto il sito.
- **Scheda prodotto**: vedi la sezione dedicata più avanti.
- **Carrello e checkout**: blocco nella pagina carrello e nel checkout.
- **Carrello laterale di Creative Elements**: vedi la sezione dedicata più avanti.

Per un posizionamento libero, il modulo implementa `WidgetInterface`:

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

## La barra nella scheda prodotto

La barra compare sotto il pulsante di aggiunta al carrello (hook `displayProductAdditionalInfo`). Oltre all'avanzamento attuale, una riga indica l'effetto dell'aggiunta del prodotto visualizzato:

- se il prodotto basta a raggiungere la soglia: «Aggiungi questo prodotto e la spedizione è gratuita»;
- altrimenti: «Con questo prodotto, ti mancheranno solo 2,50 € per la spedizione gratuita».

Il calcolo usa il prezzo della combinazione selezionata moltiplicato per la quantità inserita, sulla stessa base IVA del carrello e con i prezzi specifici del cliente. Si ripete quando il cliente cambia combinazione o quantità.

**Aggiornamento da una versione precedente.** Questa posizione parte disattivata in un negozio esistente, in modo che l'aggiornamento non cambi ciò che vedono i clienti. Attivala nella scheda Generale.

## Il carrello laterale di Creative Elements

In un negozio il cui header è costruito con Creative Elements, la barra si integra nel carrello laterale del widget **Carrello** con skin _Sidebar_, tramite l'hook `displayCEShoppingCartFooter` eseguito dal widget. La skin _Classic_ non apre un carrello laterale.

L'impostazione **Posizione nel carrello laterale** offre tre punti: sotto il titolo, sopra il riepilogo o sopra i pulsanti di checkout.

La barra si aggiorna in Ajax a ogni aggiunta al carrello e a ogni rimozione dal carrello laterale, senza ricaricare, e l'indicatore scorre dal valore precedente. Creative Elements ricostruisce solo l'elenco dei prodotti e il riepilogo: la barra resta al suo posto tra un aggiornamento e l'altro.

## Scheda Territori

La tabella elenca tutti i paesi attivi del negozio e, sotto ogni paese dotato di stati, i suoi stati rientrati. Un campo di ricerca e un filtro dei territori configurati facilitano la navigazione. Gli importi sono nella valuta predefinita.

### Ordine di risoluzione

Per un indirizzo di consegna, il modulo cerca in quest'ordine e si ferma alla prima corrispondenza: lo **stato** dell'indirizzo, poi il **paese**, poi la **soglia globale di ripiego** se attivata. Senza corrispondenza, la barra non viene mostrata.

### Casella e importo: due effetti diversi

- **Casella deselezionata**: la barra è nascosta per quel territorio, senza eredità dal paese né dalla soglia globale.
- **Casella selezionata, importo vuoto**: la regola viene eliminata, il territorio eredita dal livello superiore.
- **Casella selezionata, importo indicato**: si applica quell'importo.

**Attenzione.** Per escludere un territorio, deseleziona la casella. Svuotare l'importo produce l'effetto opposto: il territorio eredita la soglia del suo paese.

### Esempio: solo territorio metropolitano

- **Francia**: selezionata, importo `65`.
- **Corsica**: selezionata, importo vuoto; eredita i 65 €.
- **Guadalupa, Martinica, Guyana francese, Riunione, Mayotte**: deselezionate.
- **Soglia globale di ripiego**: disattivata.

## Scheda Corrieri

Tre modalità: tutti i corrieri, visualizzazione riservata ai corrieri selezionati, oppure nascondere per i corrieri selezionati. Le regole sono salvate sull'`id_reference` del corriere: PrestaShop ricrea un corriere a ogni modifica, ma il suo riferimento resta stabile.

L'impostazione **Prima della scelta del corriere** decide se la barra compare nel catalogo e nel carrello finché nessun corriere è stato scelto.

## Scheda Messaggi

Cinque messaggi si personalizzano per ogni lingua attiva:

- **Carrello vuoto** (predefinito: «Spedizione gratuita a partire da {threshold}.»)
- **Carrello in corso** (predefinito: «Ti mancano solo {amount} per la spedizione gratuita!»)
- **Soglia raggiunta**
- **Scheda prodotto: questo prodotto sblocca la spedizione gratuita**
- **Scheda prodotto: importo residuo dopo l'aggiunta del prodotto**

Sono disponibili due segnaposto: `{amount}` per l'importo mancante e `{threshold}` per la soglia. Vengono sostituiti dall'importo formattato nella valuta del visitatore, in grassetto. Il testo viene mostrato così com'è: l'HTML inserito non viene interpretato. Un campo vuoto mantiene il testo tradotto fornito con il modulo.

## Scheda Aspetto

- **Colori**: sfondo, barra, testo e messaggio di successo, con un selettore di colore e un campo esadecimale sincronizzati.
- **Icona**: camion, pacco, regalo o nessuna. Le icone sono SVG e un segno di spunta sostituisce l'icona al raggiungimento della soglia.
- **Animazione**: righe animate durante l'avanzamento, disattivate automaticamente per i visitatori che hanno chiesto al sistema di ridurre il movimento.
- **Banner richiudibile**: aggiunge un pulsante di chiusura al banner in cima alla pagina. Una volta chiuso, resta nascosto fino alla chiusura del browser. Le altre posizioni non sono interessate.

Un'**anteprima dal vivo** mostra il banner, la scheda prodotto e la soglia raggiunta, e si aggiorna a ogni modifica prima del salvataggio.

## Aggiornamento in tempo reale

Ogni posizione stampa un contenitore, anche quando la barra non ha nulla da mostrare. Dopo un evento di carrello, indirizzo, fase del checkout, combinazione o quantità, una sola richiesta ottiene la barra di tutte le posizioni della pagina, e ogni contenitore viene riempito o svuotato sul posto. Una barra nascosta al caricamento può così comparire senza ricaricare, e viceversa.

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

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

## Multinegozio e traduzioni

Le soglie portano un `id_shop`: ogni negozio ha le proprie regole. Seleziona il contesto del negozio in alto nel back office prima di aprire la configurazione.

Il modulo è fornito tradotto in italiano, francese, inglese, tedesco, spagnolo e polacco. Per i testi rivolti al cliente, la scheda Messaggi copre la maggior parte delle esigenze.

## Aggiornamento da una versione precedente

La sostituzione dello ZIP esegue automaticamente gli script di migrazione. Le tue soglie sono conservate. Le nuove opzioni partono disattivate in un negozio esistente: scheda prodotto, carrello vuoto, banner richiudibile e restrizione per gruppo. I colori salvati dalle versioni precedenti sono normalizzati nel formato `#rrggbb`, e le cache Smarty e opcache vengono svuotate.

## Risoluzione dei problemi

### La barra non compare da nessuna parte

1. La fascia di riepilogo segnala che nessun territorio ha una soglia?
2. Il modulo e le posizioni desiderate sono attivi?
3. L'obbligo di indirizzo è su _Sempre_ mentre provi senza indirizzo?
4. Ci sono gruppi di clienti selezionati di cui il tuo account di prova non fa parte?
5. L'opzione per il carrello vuoto è attiva con un carrello vuoto?

### La barra compare dove non dovrebbe

Verifica che la casella del territorio sia davvero deselezionata, e non solo che ne sia stato svuotato l'importo.

### Niente nel carrello laterale di Creative Elements

- Il widget Carrello deve usare la skin _Sidebar_.
- L'opzione «Mostra nel carrello laterale di Creative Elements» deve essere attiva.
- Dopo un aggiornamento dalla 2.1.0 o precedente, svuota la cache in **Parametri avanzati → Prestazioni**.

### L'importo non corrisponde al checkout

- L'impostazione IVA deve corrispondere alla base delle fasce del corriere.
- Un buono può riportare il carrello sotto la soglia.
- Il modulo non legge le tue fasce: riporta nel modulo ogni modifica di fascia.

### La barra non si aggiorna dopo un'aggiunta

L'aggiornamento si basa sugli eventi JavaScript di PrestaShop. Se un modulo carrello di terze parti non li emette, lancia `dffreeshipbar:refresh` dal suo codice. Controlla anche la console: un errore JavaScript a monte impedisce l'installazione del listener.

## Disinstallazione

La disinstallazione elimina entrambe le tabelle delle soglie e tutte le chiavi di configurazione con prefisso `DFFREESHIPBAR_`, messaggi compresi. Esporta entrambe le tabelle se prevedi di reinstallare.

## FAQ rapida

- **Il modulo legge PS_SHIPPING_FREE_PRICE?** Mai.
- **Il modulo legge le mie fasce corriere?** No, le soglie si inseriscono manualmente. Una sincronizzazione automatica è possibile come sviluppo su misura.
- **La mia spedizione gratuita dipende anche dal peso. È gestita?** No, il modulo misura solo un importo.
- **Posso usare il grassetto o un link in un messaggio?** No, il testo viene protetto. Gli importi dei segnaposto sono messi in grassetto automaticamente.
- **Un banner chiuso ricompare?** Alla successiva apertura del browser.

## Supporto e aggiornamenti

Il modulo include **12 mesi di aggiornamenti e supporto**. Supporto via email in francese o inglese, risposta entro 24 ore lavorative. Contatta [il supporto DataFirefly](https://www.datafirefly.com/contact/) indicando le versioni di PrestaShop, PHP e del modulo, il tema utilizzato, e il territorio e il corriere interessati.