# dffreegift: regalo omaggio alla soglia carrello, guida completa
> Guida completa del modulo dffreegift per PrestaShop 8 e 9: installazione, configurazione, funzionamento interno (CartRule nativa), personalizzazione, risoluzione dei problemi e disinstallazione. Ogni passaggio è accompagnato dai parametri esatti da…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-10-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dffreegift/index.md), [en](https://www.datafirefly.com/en/documentation/dffreegift/index.md), [es](https://www.datafirefly.com/es/documentation/dffreegift/index.md), [de](https://www.datafirefly.com/de/documentation/dffreegift/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreegift/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreegift/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreegift/index.md)
- Indice:
Guida completa del modulo **dffreegift** per PrestaShop 8 e 9: installazione, configurazione, funzionamento interno (CartRule nativa), personalizzazione, risoluzione dei problemi e disinstallazione. Ogni passaggio è accompagnato dai parametri esatti da usare in produzione.
## Panoramica
dffreegift aggiunge automaticamente un prodotto in regalo al carrello non appena viene raggiunta una soglia configurata, e lo rimuove se il carrello scende al di sotto. Il meccanismo si appoggia interamente al sistema nativo `CartRule` di PrestaShop (campo `gift_product`): il modulo non manipola mai direttamente i prezzi dei prodotti, non crea `SpecificPrice` temporanei e non inietta nulla negli hook di calcolo prezzo. Risultato: compatibilità completa con le altre promozioni, i codici sconto, le imposte e il multivaluta.
Il modulo mostra inoltre un **blocco di avanzamento** nella pagina carrello con il messaggio "Aggiungi X € per ricevere il tuo regalo", una barra colorata che si riempie man mano che la soglia si avvicina e un'animazione al superamento.
## Requisiti
- PrestaShop da 8.0 a 9.x (testato su 8.0, 8.1, 8.2, 9.0)
- PHP 8.1 minimo (8.2 e 8.3 supportate)
- Un prodotto attivo nel catalogo che farà da regalo (prodotto semplice o con declinazioni)
- Accesso amministratore al back office PrestaShop
## Installazione
1. Nel back office, vai su **Moduli → Gestore moduli → Carica un modulo**.
2. Carica il file `dffreegift-1.0.1.zip`.
3. Clicca su **Installa** e poi su **Configura**.
All'installazione il modulo esegue in background le operazioni seguenti:
- Registrazione di 5 hook: `actionCartSave`, `actionObjectCartRuleDeleteBefore`, `displayShoppingCart`, `displayCartExtraProductActions`, `displayHeader`.
- Scrittura dei valori di configurazione predefiniti (soglia 50 €, calcolo IVA inclusa, senza spese di spedizione, verifica stock attiva).
- Creazione di una `CartRule` "fantasma" con un codice univoco del tipo `DFFREEGIFT_A7B3F2D9`, visibile in **Catalogo → Sconti → Regole carrello**.
**Nota.** La CartRule creata all'installazione non ha ancora un prodotto regalo assegnato (`gift_product = 0`) e quindi non è funzionalmente attiva. Verrà sincronizzata non appena registrerai un ID di prodotto regalo nella schermata di configurazione.
**Aggiornamento dalla 1.0.0.** Carica lo zip 1.0.1 sopra la versione installata: la configurazione viene mantenuta e la regola carrello assume la sua etichetta tradotta («Omaggio»…).
## Configurazione
La schermata di configurazione si trova in **Moduli → DataFirefly Free Gift → Configura**. Tutti i parametri sono raggruppati in un unico modulo.
### Attivare il modulo
L'interruttore **Attiva il modulo** funziona da interruttore generale. In posizione _No_, il modulo resta installato ma non fa nulla: nessun aggiunta automatica, nessun blocco frontend, nessun calcolo di soglia. Utile per sospendere temporaneamente l'offerta (fine di un'operazione stagionale, per esempio) senza perdere la configurazione.
### Prodotto regalo e declinazione
Due campi da compilare nell'ordine:
1. **ID del prodotto regalo**: inserisci l'ID PrestaShop del prodotto da regalare. L'ID si trova in **Catalogo → Prodotti** (colonna ID). Dopo il primo salvataggio, il nome del prodotto compare come aiuto sotto il campo, a conferma.
2. **Declinazione**: menu a tendina delle combinazioni disponibili per il prodotto. Si popola automaticamente _dopo_ aver salvato l'ID prodotto. Scegli una declinazione specifica (per esempio "Taglia M, colore nero") oppure lascia su _Senza declinazione_ per un prodotto semplice.
**Consiglio.** Se cambi prodotto regalo in seguito, la CartRule viene risincronizzata automaticamente al salvataggio. Non devi toccare manualmente la regola nella sezione Sconti.
### Soglia di attivazione
Il campo **Soglia di attivazione** definisce l'importo carrello a partire dal quale il regalo viene aggiunto. Due parametri associati determinano la base di calcolo:
- **Calcolo IVA inclusa**: se attivo, il totale include tutte le imposte applicate al carrello. Se disattivo, la soglia viene confrontata con il totale IVA esclusa. La maggior parte dei negozi B2C ragiona IVA inclusa; i negozi B2B ragionano spesso IVA esclusa.
- **Includere le spese di spedizione**: se attivo, le spese di consegna stimate vengono aggiunte al totale prima del confronto. In pratica lo si attiva raramente, dato che le spese di spedizione non sono sempre calcolate nel momento in cui il cliente consulta il carrello (nessun corriere scelto significa 0 €).
Concretamente il totale valutato corrisponde a una chiamata nativa PrestaShop:
```
$amount = Cart::getOrderTotal(
$with_taxes = (bool) CFG_TAX_INCL,
$type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);
if (!CFG_INCLUDE_SHIPPING) {
$amount -= $giftValue; // valore dell'omaggio già offerto
}
```
Senza spese di spedizione, il valore dell'omaggio già presente nel carrello viene sottratto dal totale (dalla 1.0.1): l'omaggio non conta mai per raggiungere la soglia e viene rimosso non appena gli altri prodotti tornano sotto. Con le spese di spedizione, `Cart::BOTH` deduce già gli sconti, omaggio compreso. Gli importi provengono dai metodi nativi di PrestaShop, come il riepilogo del carrello.
### Verifica dello stock
L'interruttore **Verifica lo stock del regalo** (attivo per impostazione predefinita) sospende l'aggiunta automatica se il prodotto regalo non è disponibile. Il controllo rispetta la strategia _out of stock_ configurata globalmente in PrestaShop:
- Se il prodotto è impostato su "consenti ordini fuori stock", l'aggiunta automatica resta attiva anche a quantità 0.
- Se il prodotto rifiuta gli ordini fuori stock, l'aggiunta automatica viene sospesa quando la quantità arriva a 0.
**Raccomandazione.** Lascia questa verifica attiva. Disattivare il controllo può portare a ordini bloccati al checkout per rottura di stock del regalo, con esperienza cliente degradata e intervento manuale necessario.
### Restrizione per gruppi clienti
La griglia **Gruppi clienti idonei** elenca tutti i gruppi del negozio con una casella per gruppo. Due comportamenti:
- **Nessuna casella selezionata**: tutti i clienti sono idonei, compresi i visitatori non identificati (a condizione che il gruppo predefinito `PS_UNIDENTIFIED_GROUP` non sia escluso, che è il comportamento predefinito).
- **Una o più caselle selezionate**: solo i clienti membri di almeno un gruppo selezionato vedono il blocco di avanzamento e beneficiano dell'aggiunta automatica.
Casi d'uso tipici:
- Regalo riservato al gruppo "Professionisti" per una clientela B2B.
- Regalo riservato al gruppo "VIP" per un programma fedeltà.
- Regalo offerto a tutti _tranne_ ai rivenditori (selezionare tutti i gruppi tranne quello dei rivenditori).
### Opzioni di visualizzazione
Due interruttori indipendenti controllano l'aspetto del blocco frontend:
- **Mostra il messaggio di avanzamento**: attiva o disattiva completamente il blocco nella pagina carrello. In posizione _No_, l'aggiunta automatica continua a funzionare ma nessun messaggio compare lato cliente (utile se preferisci gestire la visualizzazione dal tuo tema).
- **Mostra la barra di avanzamento**: attiva o disattiva la barra colorata sotto il messaggio. Il testo resta visibile.
Configurazione di DataFirefly Free Gift: prodotto omaggio, soglia del carrello, calcolo IVA inclusa, spedizione e gruppi di clienti
## Come funziona tecnicamente
### La CartRule fantasma
Invece di manipolare i prezzi dei prodotti, dffreegift sfrutta il meccanismo nativo PrestaShop del regalo tramite `CartRule`. All'installazione viene creata una regola con le seguenti proprietà:
- `code` = `DFFREEGIFT_A7B3F2D9` (suffisso generato casualmente all'installazione)
- `gift_product` = 0 (aggiornato a ogni salvataggio della configurazione)
- `gift_product_attribute` = 0 (aggiornato a ogni salvataggio della configurazione)
- `quantity` = 999.999 e `quantity_per_user` = 999.999 (praticamente illimitato)
- `date_from` = adesso, `date_to` = +50 anni
- `active` = 1, nessun codice, nessuno sconto, nessuna restrizione prodotto o categoria
Quando la soglia viene raggiunta, il modulo associa questa regola al carrello tramite `Cart::addCartRule($id)`. PrestaShop si occupa poi del resto:
- Inserimento di una riga carrello con `gift = 1` e `price = 0`.
- Visualizzazione nel riepilogo carrello con un badge "Regalo".
- Presa in carico al momento della conversione in ordine.
- Snapshot nello storico dell'ordine (il regalo resta visibile anche se in seguito cambi prodotto regalo).
Quando il carrello scende sotto la soglia, il modulo stacca la regola tramite `Cart::removeCartRule($id)`. La riga regalo viene rimossa nella stessa richiesta.
Regola carrello PrestaShop creata dal modulo, con l'azione che invia il prodotto omaggio
Checkout: il prodotto omaggio compare nel riepilogo dell'ordine con il relativo sconto
### Gli hook utilizzati
- **actionCartSave**: hook principale. Chiamato a ogni salvataggio del carrello (aggiunta, modifica, rimozione, login cliente con fusione del carrello). Il modulo calcola il totale e decide se associare o staccare la regola. Un flag statico `self::$syncing` impedisce la ricorsione se l'associazione della regola innesca a sua volta un salvataggio.
- **actionObjectCartRuleDeleteBefore**: auto-riparazione. Se un amministratore elimina manualmente la regola fantasma da **Catalogo → Sconti**, questo hook rileva l'eliminazione e azzera l'ID nella configurazione. La sincronizzazione successiva ricreerà una regola pulita.
- **displayHeader**: registra il CSS e il JS frontend (`views/css/dffreegift.css` e `views/js/dffreegift.js`).
- **displayShoppingCart**: mostra il blocco di avanzamento nella pagina carrello.
- **displayCartExtraProductActions**: riservato a evoluzioni future (badge sulla riga regalo).
### Il calcolo della soglia
A ogni chiamata di `syncCartGift()`, il modulo verifica nell'ordine:
1. Il modulo è attivo? (altrimenti esce)
2. Il cliente è idoneo secondo i gruppi configurati? (altrimenti stacca se associata)
3. Il prodotto regalo è valido (esiste, è attivo, è in stock se la verifica è attiva)? (altrimenti stacca)
4. Calcolo del totale in base a IVA inclusa/esclusa e spese di spedizione incluse/escluse.
5. Confronto con la soglia con una tolleranza di arrotondamento di 0,001 €.
6. Associa la regola se la soglia è raggiunta e non è ancora associata. Stacca se si scende sotto la soglia ed è associata.
## Blocco di avanzamento frontend
Il blocco compare automaticamente nella pagina carrello, tra il riepilogo prodotti e il totale. Due stati visivi:
- **In attesa** (soglia non raggiunta): sfondo grigio chiaro, messaggio "Aggiungi X,XX € per ricevere il tuo regalo", barra arancione che si riempie man mano che la soglia si avvicina.
- **Obiettivo raggiunto** (soglia superata): sfondo verde chiaro, messaggio "Regalo aggiunto al tuo carrello!", barra piena in verde. Un'animazione `pulse` si attiva al passaggio dallo stato _in attesa_ a _raggiunto_.
Dalla versione 1.0.1 il blocco si aggiorna senza ricaricare la pagina a ogni modifica del carrello (quantità, articolo rimosso). Lo sconto che rende gratuito l'omaggio appare al cliente con un'etichetta tradotta: «Omaggio», «Free gift», «Cadeau offert», «Regalo gratuito», «Gratis-Geschenk», «Brinde», «Prezent gratis» o «Gratis cadeau», a seconda della lingua.
Carrello: messaggio con l'importo mancante per ricevere l'omaggio e barra di avanzamento
Soglia raggiunta: il prodotto omaggio viene aggiunto automaticamente al carrello e reso gratuito dallo sconto Omaggio
Carrello di nuovo sotto la soglia: l'omaggio viene rimosso automaticamente e il messaggio si aggiorna senza ricaricare la pagina
### Personalizzare i colori
I colori sono definiti in `views/css/dffreegift.css`. Per personalizzare senza modificare il modulo (cosa che cancellerebbe le tue modifiche agli aggiornamenti), sovrascrivi le classi nel CSS del tuo tema:
```
.dffreegift-progress {
border-color: #tuo-colore;
background: #tuo-sfondo;
}
.dffreegift-progress--reached {
background: #tuo-verde-chiaro;
border-color: #tuo-verde;
}
.dffreegift-progress__bar-fill {
background: linear-gradient(90deg, #colore1, #colore2);
}
```
### Personalizzare i testi
I testi mostrati lato cliente sono traducibili tramite il meccanismo standard di PrestaShop. Vai su **Internazionale → Traduzioni**, seleziona "Traduzioni dei moduli", scegli _dffreegift_ e la lingua, poi cerca il dominio `Modules.Dffreegift.Shop`. Le stringhe disponibili:
- _"Aggiungi %amount% per ricevere il tuo regalo"_: messaggio in attesa (`%amount%` viene sostituito automaticamente dall'importo restante formattato secondo valuta e locale).
- _"Regalo aggiunto al tuo carrello!"_: messaggio obiettivo raggiunto.
- _"Avanzamento verso il regalo"_: etichetta ARIA della barra (letta dagli screen reader).
Il modulo è fornito tradotto in 8 lingue, back office e front office: francese (lingua di origine), inglese, spagnolo, tedesco, italiano, portoghese, polacco e olandese. Queste traduzioni sono una base: puoi modificarle come indicato sopra.
## Convivenza con altre promozioni
Dato che il regalo viene aggiunto tramite una `CartRule` nativa, convive normalmente con qualsiasi altra `CartRule`. Comportamenti attesi:
- **Altri codici sconto cliente** (sconto percentuale, importo fisso, spedizione gratuita): si applicano normalmente in parallelo al regalo. Il regalo non consuma lo sconto e viceversa.
- **Altra regola con gift_product** configurata altrove: PrestaShop tratta le due come regole indipendenti e aggiunge entrambi i regali. Attenzione se cumuli più moduli regalo.
- **Regola con product_restriction** che esclude il prodotto regalo: prevale la regola restrittiva. Il regalo non viene aggiunto se un'altra regola attiva lo esclude esplicitamente.
- **Regola con cart_rule_restriction**: se un'altra regola vieta l'uso della nostra per restrizione incrociata, l'aggiunta automatica viene bloccata (comportamento nativo PrestaShop).
**Nota.** La soglia di dffreegift viene valutata sul totale _senza regalo_. Se hai un'altra cart rule che sconta il totale prima che dffreegift lo valuti, il confronto avviene sul totale _dopo_ lo sconto. Un carrello da 60 € con uno sconto di 15 € scende a 45 € e non attiverà una soglia di 50 €.
## Multinegozio
Il modulo funziona con la configurazione multinegozio di PrestaShop nel **contesto negozio predefinito**. Le configurazioni (soglia, prodotto regalo, opzioni) sono memorizzate tramite `Configuration::updateValue`, che rispetta il contesto negozio corrente. La `CartRule` creata all'installazione è associata al negozio attivo al momento dell'installazione.
Per un deployment multinegozio con _regali diversi per negozio_, occorre al momento installare e configurare il modulo in ciascun contesto negozio separatamente. Contatta il supporto per una variante con scoping esplicito per `id_shop`.
## Risoluzione dei problemi
### Il regalo non viene aggiunto al carrello
Verifica nell'ordine:
1. Il modulo è effettivamente attivo? (Moduli → Configura → interruttore _Attiva il modulo_).
2. Il prodotto regalo è valido? (ID corretto, prodotto attivo, in stock se la verifica stock è attiva).
3. Il cliente appartiene a un gruppo autorizzato? (se hai limitato ai gruppi, un visitatore non identificato che non è in nessun gruppo autorizzato non vedrà nulla).
4. La soglia è realmente raggiunta? Ricalcola manualmente il totale secondo i tuoi parametri (IVA inclusa/esclusa, con/senza spedizione).
5. La `CartRule` fantasma esiste ed è attiva? Vai su **Catalogo → Sconti → Regole carrello** e cerca `DFFREEGIFT_`.
### Il blocco di avanzamento non compare nella pagina carrello
Cause frequenti:
- L'interruttore _Mostra il messaggio di avanzamento_ è su _No_.
- Il cliente non è idoneo secondo i gruppi clienti configurati.
- Il prodotto regalo non è valido (non esiste, è inattivo o è esaurito con la verifica stock attiva).
- Il tuo tema personalizzato non chiama l'hook `displayShoppingCart`. Verifica con il comando `grep -r "displayShoppingCart" themes/tuo-tema/` oppure in **Moduli → Posizioni**.
### La CartRule è sparita dal back office
Se qualcuno ha eliminato la regola da **Catalogo → Sconti**, l'hook `actionObjectCartRuleDeleteBefore` ha rilevato l'eliminazione e azzerato la configurazione. Alla successiva sincronizzazione del carrello (quindi al prossimo prodotto aggiunto da un cliente) viene creata automaticamente una nuova regola con un nuovo codice `DFFREEGIFT_xxxxxxxx`.
Per forzare subito la rigenerazione senza aspettare un cliente:
1. Vai su **Moduli → DataFirefly Free Gift → Disattiva**.
2. Poi **Attiva** di nuovo. Questo ricrea una regola pulita.
### Errori nei log di PrestaShop
Il modulo registra le eccezioni in **Parametri avanzati → Log** con il prefisso `[dffreegift]`. Un messaggio tipico in caso di problema:
```
[dffreegift] actionCartSave error:
```
Questi errori non interrompono mai il funzionamento del carrello, sono solo informativi. In caso di log ricorrente, inoltra il messaggio completo al supporto.
### La soglia sembra calcolata male
Il calcolo dipende strettamente dai tuoi parametri _Calcolo IVA inclusa_ e _Includere le spese di spedizione_. Per verificare cosa restituisce PrestaShop:
- IVA inclusa senza spedizione: corrisponde al _Subtotale prodotti IVA inclusa_ mostrato nel riepilogo carrello.
- IVA inclusa con spedizione: corrisponde al _Totale IVA inclusa_ (prodotti più spese di spedizione se è selezionato un corriere).
- IVA esclusa senza spedizione: corrisponde al _Subtotale prodotti IVA esclusa_.
- IVA esclusa con spedizione: corrisponde al _Totale IVA esclusa_ (prodotti più spese di spedizione IVA esclusa).
Se noti uno scarto, confronta con la riga esatta del riepilogo carrello: è molto probabile che derivi dalle spese di spedizione non ancora calcolate (il cliente non ha ancora scelto un corriere, quindi le spese sono a 0 €).
Quando l'omaggio è già nel carrello, il subtotale mostrato lo include al prezzo normale, compensato dalla riga di sconto «Omaggio». Il modulo confronta con la soglia il totale _senza l'omaggio_.
## Disinstallazione
Vai su **Moduli → Gestore moduli → DataFirefly Free Gift → Disinstalla**. La disinstallazione elimina:
- La `CartRule` fantasma e tutte le sue associazioni ai carrelli (i carrelli in corso perderanno automaticamente il regalo).
- Tutte le chiavi di configurazione con il prefisso `DFFREEGIFT_`.
**Attenzione.** La disinstallazione non ripristina i regali negli ordini già effettuati: questi mantengono il loro snapshot originale con il regalo correttamente registrato. Sono interessati solo i carrelli in corso.
## FAQ rapida
- **Il regalo compare nel mini-carrello dell'header?** No, solo nella pagina carrello (hook `displayShoppingCart`). Il mini-carrello è gestito in modo diverso da ogni tema e servirebbe un'integrazione specifica tema per tema. Su richiesta al supporto.
- **Posso offrire più regali con più soglie (per esempio regalo A a 50 €, regalo B a 100 €)?** No, la versione 1.0.1 gestisce un solo regalo con una sola soglia. Per più livelli, contatta il supporto.
- **Il regalo è incluso nei rimborsi?** Come ogni prodotto regalo nativo PrestaShop, il regalo compare nell'ordine a prezzo 0. In caso di rimborso parziale, il regalo resta nell'ordine senza impatto finanziario.
- **Posso modificare direttamente il file dffreegift.php?** Tecnicamente sì (codice non cifrato), ma gli aggiornamenti ufficiali sovrascriveranno le tue modifiche. Crea un modulo override per qualsiasi personalizzazione profonda.
## Supporto e aggiornamenti
Il modulo include **12 mesi di aggiornamenti e supporto** dalla data di acquisto. Supporto via email in francese o in inglese, risposta entro 24 ore lavorative.
Per qualsiasi domanda o anomalia, contatta [il supporto DataFirefly](https://www.datafirefly.com/it/contattaci/) precisando:
- Versione di PrestaShop (visibile in **Parametri avanzati → Informazioni**)
- Versione di PHP
- Versione del modulo dffreegift installata
- Descrizione del comportamento osservato rispetto a quello atteso
- Estratto dei log PrestaShop se applicabile (`[dffreegift]`)