Smart Offers — Documentazione completa

Smart Offers è un modulo PrestaShop 8 che permette di creare offerte 1+1, pacchi all’ingrosso, pacchetti multi-prodotto e offerte a scelta — con aggiunta automatica dei prodotti regalo al carrello e presentazione curata sulla scheda prodotto.

Panoramica

Smart Offers copre i quattro formati di offerte raggruppate più utilizzati nell’e-commerce in un solo modulo, senza configurazione complessa. Il motore valuta il carrello ad ogni modifica, aggiunge automaticamente i prodotti regalo non appena le condizioni sono soddisfatte e crea una regola del carrello che rende quelle unità gratuite — l’esperienza del cliente è immediata e leggibile.

Installazione

1. Scarica il file dfoffers-vX.Y.Z.zip dalla tua area cliente DataFirefly
2. Nel back office di PrestaShop, vai su Moduli → Gestione moduli
3. Clicca sul pulsante Carica un modulo in alto
4. Trascina il file ZIP o cliccaci sopra per selezionarlo
5. L’installazione è automatica: le tabelle vengono create, gli hook registrati, e una nuova scheda Catalogo → Offerte raggruppate appare nel menu

I quattro tipi di offerte

1+1 sullo stesso prodotto

Il formato virale del buy-one-get-one: il cliente acquista un’unità di un prodotto e riceve un’altra unità dello stesso prodotto in regalo. Configura:

• Un solo prodotto (utilizzato sia come trigger che come ricompensa)
• La quantità da acquistare per attivare l’offerta (in genere 1)
• La quantità in regalo (in genere 1)

Esempio tipico: “Per 1 paio di calzini acquistato, il secondo è in regalo.” Quando il cliente aggiunge il paio al carrello, il motore aggiunge automaticamente un secondo e applica uno sconto pari al prezzo unitario.

Compra X, ricevi Y in regalo (prodotti diversi)

Formato bundle: più prodotti trigger distinti devono essere presenti nel carrello affinché l’offerta si attivi, e uno o più prodotti diversi vengono allora regalati. Configura:

• L’elenco dei prodotti trigger con le rispettive quantità
• L’elenco dei prodotti regalo con le rispettive quantità

Esempio tipico: “Compra una crema giorno e un siero insieme, ricevi un campione di maschera in regalo.” Il motore verifica che tutti i trigger siano presenti prima di attivare l’offerta.

Scelta tra varianti

Formato di composizione libera: definisci un insieme di prodotti o varianti candidate tra cui il cliente compone il proprio lotto. Il motore identifica automaticamente le unità più economiche del carrello come unità regalate, cosa che corrisponde all’interpretazione commerciale standard del buy-N-get-M.

• L’elenco dei prodotti o varianti candidate
• Il numero di unità da acquistare in questo insieme
• Il numero di unità regalate (le più economiche)

Esempio tipico: “3 t-shirt acquistate dalla nostra selezione, la più economica è gratuita.” Il cliente compone il proprio lotto, il motore non tocca il suo carrello ma applica uno sconto sulle unità più economiche.

Pacco all’ingrosso

Formato B2B e smaltimento di magazzino: per ogni lotto di X unità acquistate di un prodotto, il cliente riceve Y unità gratuite di un altro prodotto. Configura:

• Il prodotto trigger con la quantità di scaglione (ad esempio 10)
• Il prodotto regalo con la quantità offerta (ad esempio 20)

Esempio tipico: “Per 10 bottiglie di vino acquistate, 2 bicchieri in regalo.” Pratico per i fornitori che vogliono spingere un prodotto complementare o smaltire scorte ferme attaccandole a un prodotto che vende bene.

Crea la tua prima offerta

Dal back office, vai su Catalogo → Offerte raggruppate poi clicca su Nuova offerta.

Passo 1: scegliere il tipo

Quattro carte visive presentano i tipi disponibili con una breve descrizione. Clicca su quella che corrisponde alla tua operazione commerciale. Il modulo si adatta automaticamente e mostra solo i campi rilevanti per quel tipo.

Passo 2: nominare e dare un badge all’offerta

Compila:

• Nome dell’offerta (obbligatorio): ciò che il cliente vede sul banner. Disponibile in cinque lingue.
• Testo del badge (opzionale, max 64 caratteri): breve messaggio mostrato nella pill in alto del banner (ad esempio 1+1 GRATIS, OFFERTA SPECIALE, BLACK FRIDAY).
• Colore del badge: sei preset DataFirefly disponibili più un selettore di colore libero. Il colore è utilizzato sia per il banner della scheda prodotto SIA per l’etichetta regalo lato carrello.

Passo 3: aggiungere i prodotti trigger

Clicca su Aggiungi un prodotto trigger. Si apre una modale di ricerca con un campo che interroga il tuo catalogo in tempo reale (debounce di 250 ms dopo l’ultimo tasto). Digita un nome, una referenza o un EAN; i risultati appaiono immediatamente.

Clicca su un prodotto per aggiungerlo. Se il prodotto ha varianti, queste appaiono come pulsanti sotto il risultato — clicca su quella che ti interessa per aggiungerla direttamente. Specifica la quantità richiesta nel campo a destra della riga.

Passo 4: aggiungere i prodotti regalo

Stessa procedura per i prodotti regalo. Questa sezione è nascosta per il tipo Scelta tra varianti, poiché le varianti servono sia da candidate che da ricompense.

Passo 5: regole specifiche

• Cumulabile: se attivato, l’offerta si applica più volte per ogni lotto trigger. Senza cumulo, l’offerta si applica una sola volta a prescindere dal numero di unità. Disattivato di default per proteggere i tuoi margini.
• Per il tipo Scelta tra varianti, appaiono due campi aggiuntivi: quante unità il cliente deve acquistare e quante sono in regalo.

Passo 6: attivazione

• Date di validità: lascia vuoto per un’offerta permanente. Indica la data di inizio o di fine per automatizzare l’attivazione.
• Priorità: se più offerte possono applicarsi simultaneamente, quella con la priorità più bassa viene valutata per prima.
• Stato: interruttore on/off, attivato di default. Pratico per disattivare temporaneamente un’offerta senza eliminarla.

Passo 7: negozi (se multi-negozio)

Spunta i negozi su cui l’offerta deve essere disponibile. Non spuntare nulla equivale ad attivare l’offerta su tutti i negozi.

Come funziona il motore di aggiunta automatica

Il motore si aggancia all’hook PrestaShop actionCartSave e si esegue ad ogni modifica del carrello (aggiunta, rimozione, cambio di quantità, fusione al login).

1. Recupera tutte le offerte attive per il negozio corrente
2. Per ogni offerta, calcola la quantità pagata di ciascun prodotto trigger (quantità totale del carrello meno ciò che il motore ha già aggiunto automaticamente in una valutazione precedente)
3. Valuta se le condizioni dell’offerta sono soddisfatte
4. In tal caso, aggiunge i prodotti regalo mancanti al carrello tramite Cart::updateQty
5. Crea o aggiorna una regola del carrello (CartRule) con uno sconto fisso IVA inclusa pari al valore delle unità offerte
6. Registra nella tabella ps_dfoffers_cart_auto le unità che ha aggiunto, per distinguerle dalle unità che il cliente ha aggiunto da solo

Revoca pulita

Se il cliente rimuove un prodotto trigger o riduce la sua quantità sotto la soglia, il motore rivaluta l’offerta al successivo actionCartSave. Se la condizione non è più soddisfatta, rimuove le unità che aveva aggiunto automaticamente (senza toccare le unità che il cliente aveva aggiunto da solo grazie al tracking) ed elimina la regola del carrello associata.

Visualizzazione sulla scheda prodotto

Su ogni scheda prodotto trigger, un banner con gradiente viene mostrato tramite l’hook displayProductAdditionalInfo. Contiene:

• Un badge pill bianco con icona regalo, contenente il testo del badge
• Il titolo dell’offerta
• Un messaggio dinamico che dipende dal tipo di offerta (“Aggiungi 1 prodotto, ricevi 1 gratis”, “Per 10 unità acquistate, 20 unità in regalo”, ecc.)
• Una griglia con le miniature cliccabili dei prodotti coinvolti, separate in due gruppi Acquista / Ricevi in regalo con un separatore SVG circolare tra di esse

Il colore del banner riprende quello del badge configurato nell’offerta. La presentazione è responsive: su mobile, i due gruppi si impilano verticalmente e il separatore ruota per puntare verso il basso.

Visualizzazione nel carrello

Dalla versione 1.1.0, due indicatori distinti aiutano il cliente a identificare i prodotti regalo nel suo carrello.

Etichetta regalo su ogni riga

Su ogni riga del carrello che contiene unità aggiunte automaticamente da un’offerta, appare una piccola etichetta colorata 🎁 ×N gratis accanto alle azioni della riga. Il colore riprende quello del badge dell’offerta, e l’etichetta indica quante unità di questa riga sono gratuite (utile quando una parte della quantità è pagata e l’altra offerta, ad esempio in un 1+1 stesso prodotto).

Footer del carrello dettagliato

In fondo alla griglia dei prodotti, un blocco verde riepiloga le offerte attivate nel carrello. Per ogni offerta, il blocco mostra:

• Il nome dell’offerta e il suo testo di badge (in pill colorata)
• L’elenco dei prodotti offerti da questa offerta, sotto forma di chip visivi con miniatura rotonda, nome e quantità
• Ogni chip è cliccabile e rimanda alla scheda del prodotto regalo

Il cliente può così verificare a colpo d’occhio cosa ha ottenuto gratuitamente e grazie a quale operazione commerciale.

Casi particolari e comportamenti

Perché 1+1 sullo stesso prodotto è gestito specificamente

Quando il prodotto trigger è anche il prodotto regalo, molti moduli di offerte raggruppate sul mercato commettono l’errore di identificare l’unità pagata del cliente come se fosse già l’unità offerta, e applicano lo sconto su quella unità — alla fine, il cliente paga zero per un’unità invece di pagare per una e riceverne una seconda gratis.

Smart Offers gestisce questo caso con una logica precisa: la quantità target nel carrello vale quantità pagata dal cliente + quantità regalo. Quando il cliente aggiunge un’unità, il motore ne aggiunge una seconda affinché il carrello contenga due unità, e lo sconto si applica solo sulla seconda unità. Il cliente paga quindi il prezzo di un’unità per averne due nel suo carrello.

Cumulo dei lotti (opzione stackable)

Senza cumulo, l’offerta si applica una sola volta a prescindere dal numero di lotti trigger presenti nel carrello. Se il cliente acquista 5 unità di un prodotto con un’offerta 1+1 e stackable disattivato, riceverà 1 unità in regalo (non 5).

Con il cumulo attivato, il motore moltiplica il numero di lotti di ricompensa per il numero intero di lotti trigger presenti. Per la stessa offerta 1+1 con stackable attivato e 5 unità nel carrello, il cliente riceverà 5 unità in regalo (carrello finale: 10 unità, 5 pagate).

Magazzino e indisponibilità

L’aggiunta dei prodotti regalo al carrello passa per Cart::updateQty, che rispetta le regole di magazzino native di PrestaShop. Se un prodotto regalo è esaurito e il negozio non consente l’ordine senza scorta, l’aggiunta fallisce silenziosamente e lo sconto non viene applicato — la condizione resta pronta ad attivarsi non appena il prodotto torna disponibile.

Più offerte simultanee sullo stesso carrello

Ogni offerta genera la propria regola del carrello con partial_use attivato. Questo permette di accumulare più offerte concorrenti sullo stesso carrello senza conflitti, e resta compatibile con i codici sconto classici che i tuoi clienti possono inserire.

Architettura tecnica

Hook utilizzati

• displayProductAdditionalInfo: banner sulla scheda prodotto
• displayShoppingCartFooter: footer dettagliato sulla pagina del carrello
• displayCartExtraProductActions: etichetta regalo su ogni riga del carrello
• actionCartSave: motore di valutazione e aggiunta automatica
• actionFrontControllerSetMedia e actionAdminControllerSetMedia: iniezione di CSS e JS
• actionObjectProductDeleteAfter: pulizia automatica delle offerte che fanno riferimento a un prodotto eliminato

Tabelle aggiunte

• ps_dfoffers_offer: configurazione di ciascuna offerta (tipo, date, priorità, cumulo)
• ps_dfoffers_offer_lang: nome, badge e descrizione tradotti per lingua
• ps_dfoffers_trigger: prodotti trigger di ciascuna offerta
• ps_dfoffers_reward: prodotti regalo di ciascuna offerta
• ps_dfoffers_shop: associazione offerta / negozio in multi-negozio
• ps_dfoffers_cart_auto: tracking delle unità aggiunte automaticamente per carrello e per offerta, con l’identificativo della regola del carrello generata

Tutte le tabelle utilizzano il prefisso configurato nella tua installazione PrestaShop (ps_ di default).

Sovrascrivere i template nel tuo tema

Il CSS del modulo è isolato sotto il prefisso .dfoffers- per evitare conflitti con il tuo foglio di stile. Se desideri modificare il rendering, copia i template da /modules/dfoffers/views/templates/hook/ verso /themes/il-tuo-tema/modules/dfoffers/views/templates/hook/ e personalizzali. Tre template sono disponibili:

• product-banner.tpl: banner sulla scheda prodotto
• cart-offer.tpl: blocco riepilogo nel footer del carrello
• cart-line-gift.tpl: etichetta regalo inline sulle righe del carrello

Aggiornare il modulo

Per aggiornare a una nuova versione, carica semplicemente il nuovo ZIP dal Gestore moduli. PrestaShop rileva il cambio di versione in config.xml ed esegue automaticamente gli script di aggiornamento presenti in /upgrade/upgrade-X.Y.Z.php, che si occupano ad esempio di registrare nuovi hook aggiunti tra le versioni.

Risoluzione dei problemi

I prodotti regalo non vengono aggiunti al carrello

1. Svuota la cache PrestaShop in Parametri avanzati → Prestazioni
2. Verifica che l’hook actionCartSave contenga il modulo in Design → Posizioni
3. Verifica che il prodotto regalo sia disponibile (non esaurito se gli ordini senza scorta sono vietati, non disattivato, assegnato al negozio corrente)
4. Consulta Parametri avanzati → Log cercando dfoffers: il motore traccia la sua esecuzione ad ogni modifica del carrello

Lo sconto non viene applicato nonostante l’aggiunta del prodotto

Verifica nei log la riga checkValidity che segue la creazione della regola del carrello. PrestaShop indica con precisione perché una regola viene rifiutata (esaurito, restrizione cliente, valuta diversa, ecc.).

L’etichetta regalo non appare sulle righe del carrello

Verifica che il tuo tema implementi correttamente l’hook displayCartExtraProductActions in cart-detailed-product-line.tpl. I temi Classic e la maggior parte dei temi commerciali lo contengono. Se usi un tema personalizzato che non lo implementa, aggiungi la seguente riga nel file cart-detailed-product-line.tpl al livello desiderato:

{hook h='displayCartExtraProductActions' product=$product}

Domande frequenti

Il modulo è compatibile con PrestaShop 9?

No, la versione 1.x copre solo PrestaShop da 8.0 a 8.99. Una versione 2.x compatibile con PrestaShop 9 è pianificata separatamente a causa dei cambiamenti significativi nell’API dei controller in PS 9.

Qual è l’impatto sulle prestazioni?

Il motore esegue una query SQL per offerta attiva sul negozio, poi valuta le condizioni in memoria. Su un catalogo con una decina di offerte attive, la valutazione completa richiede in media meno di cinquanta millisecondi.

Posso usare il modulo con un tema headless?

Il motore di aggiunta automatica è indipendente dal tema e funziona per qualsiasi front-end che passi per Cart::updateQty o l’API REST di PrestaShop. Il banner della scheda prodotto e l’etichetta regalo del carrello sono hook Smarty nativi che richiedono un tema classico per essere mostrati. Per un front headless, puoi esporre i dati tramite un’API custom che interroga direttamente ps_dfoffers_offer e ps_dfoffers_cart_auto.

Il modulo gestisce più valute?

Sì. La regola del carrello generata per ciascuna offerta utilizza la valuta del carrello corrente. Se il cliente cambia valuta, la regola viene rigenerata al valore corretto al successivo actionCartSave.