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 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.0.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.

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.

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:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Questo garantisce che il valore usato per il confronto sia esattamente identico a quello mostrato nel riepilogo carrello di PrestaShop.

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.

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.

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.

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.

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).

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).

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: <descrizione dell'errore>

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 €).

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_.

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.0 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 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])