# DF Samples: ordine di campioni prodotto (PrestaShop 8 e 9) > Panoramica DF Samples aggiunge un pulsante «Ordina un campione» alle schede prodotto. Il campione può essere gratuito o costare pochi euro, per il prodotto o per la combinazione scelta dal… - Pagina: - Lingua: it - Aggiornato il: 2026-10-13 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dfsamples/index.md), [en](https://www.datafirefly.com/en/documentation/dfsamples/index.md), [es](https://www.datafirefly.com/es/documentation/dfsamples/index.md), [de](https://www.datafirefly.com/de/documentation/dfsamples/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsamples/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsamples/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsamples/index.md) - Indice: ## Panoramica DF Samples aggiunge un pulsante «Ordina un campione» alle schede prodotto. Il campione può essere gratuito o costare pochi euro, per il prodotto o per la combinazione scelta dal cliente. Il modulo crea un prodotto campione nascosto per ogni prodotto iscritto, blocca la quantità a 1, applica limiti per cliente sul contenuto del carrello, misura la conversione da campione ad acquisto e invia un'email di follow-up con un buono sconto opzionale. Il modulo è compatibile con PrestaShop da 8.0 a 9.x, multinegozio e multilingua, e non usa alcun override del core. Questa documentazione riguarda la versione 1.1.0. ## Installazione 1. Nel back-office, vai su **Moduli > Gestione moduli**. 2. Fai clic su **Carica un modulo** e trascina il file `dfsamples.zip`. 3. Apri **Catalogo > Campioni (DF)**: in questa pagina trovi l'elenco dei prodotti, la dashboard e le impostazioni. All'installazione, il modulo crea: - tre tabelle: `dfsamples_product`, `dfsamples_order` e `dfsamples_cart`; - una categoria **Campioni** disattivata, sotto Home, accessibile a tutti i gruppi di clienti, che conterrà i prodotti campione; - le impostazioni predefinite e un token di sicurezza per il cron; - la scheda di amministrazione **Catalogo > Campioni (DF)**; - una copia del modello email inglese per ogni lingua installata che non ne ha uno. Si registra su 12 hook, tra cui displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder e actionOrderStatusPostUpdate. ## Aggiornare dalla versione 1.0.0 Carica il nuovo ZIP sopra il precedente dalla gestione moduli. Lo script di aggiornamento: - aggiunge la tabella `dfsamples_cart` e le nuove colonne; - registra i nuovi hook; - crea la categoria Campioni e vi sposta i prodotti campione esistenti; - li rinomina nel nuovo formato e aggiunge le immagini mancanti (su PrestaShop 9 la versione 1.0.0 non copiava l'immagine); - conserva i prodotti iscritti, le statistiche e lo storico dei follow-up. Se un passaggio non riesce, il pulsante **Risincronizza i campioni**, in alto nella pagina del modulo, ripete la sincronizzazione di tutti i prodotti campione. ## Aggiungere un prodotto al programma campioni 1. Apri **Catalogo > Campioni (DF)** e fai clic su **Aggiungi un prodotto**. 2. Cerca il prodotto per nome o riferimento e selezionalo. I prodotti già iscritti e i prodotti campione sono esclusi dai risultati. 3. Inserisci il **Prezzo del campione (IVA incl.)**. Inserisci 0,00 per un campione gratuito. 4. Imposta il **Massimo per cliente** per questo prodotto nella finestra mobile (0 = illimitato). 5. Attiva **Campione per variante** se il prodotto ha combinazioni e il cliente deve sceglierne una (vedi sotto). 6. Salva. ### Cosa fa il modulo al salvataggio Il modulo crea un prodotto campione nascosto, o aggiorna quello esistente: - nome tradotto nel formato «Campione: Nome del prodotto» (Échantillon, Sample, Muestra, Muster nelle altre lingue); - riferimento nel formato SMPL seguito dall'ID del prodotto di origine; - prezzo IVA esclusa calcolato dal prezzo inserito e dalla regola fiscale del prodotto di origine; - immagine di copertina del prodotto di origine copiata in tutti i formati immagine; - categoria predefinita: la categoria Campioni; - visibilità «da nessuna parte»: il prodotto non compare né negli elenchi né nella ricerca; - ordini consentiti anche senza stock, per non bloccare mai una richiesta; - peso preso dall'impostazione globale, usato dai corrieri. Se in seguito modifichi il prezzo, l'opzione variante, il peso globale o lo stato attivo, il prodotto campione viene risincronizzato. Se è stato eliminato manualmente dal catalogo, viene ricreato al salvataggio successivo. ## Campione per variante Con l'opzione **Campione per variante**, il cliente sceglie la combinazione nella scheda prodotto come per un acquisto normale, poi fa clic sul pulsante, che diventa «Ordina un campione di questa variante». - La combinazione viene registrata sulla riga del campione, ad esempio «Formato: A4, Carta: Patinata 300 g». Compare in un campo «Variante» del carrello, dell'ordine, della fattura e dell'email di follow-up. - Ogni combinazione occupa una riga separata. La stessa combinazione non può essere aggiunta due volte. - Il massimo per cliente del prodotto è conteggiato per combinazione. - Il prezzo del campione è lo stesso per tutte le combinazioni del prodotto. Il prodotto campione resta un prodotto semplice, senza combinazioni né stock proprio. La combinazione è un testo di personalizzazione aggiunto dal modulo, quindi le tue combinazioni non vengono duplicate. ## Impostazioni Le impostazioni si trovano sotto l'elenco dei prodotti, nella pagina **Catalogo > Campioni (DF)**. ### Impostazioni generali - **Posizione del pulsante**: sotto il pulsante di aggiunta al carrello (displayProductActions), nel blocco informazioni aggiuntive (displayProductAdditionalInfo), oppure solo posizione personalizzata (displayDfSamplesButton, vedi la sezione successiva). - **Prezzo del campione predefinito (IVA incl.)**: valore proposto quando aggiungi un campione. - **Peso del campione**: in chilogrammi, applicato a tutti i prodotti campione, usato per le spese di spedizione. - **Account cliente obbligatorio**: attivo per impostazione predefinita. I limiti per cliente si applicano in modo affidabile solo ai clienti identificati. - **Sconti per gruppo clienti sui campioni**: applicare (comportamento predefinito di PrestaShop) o non applicare. Vedi «Prezzi e sconti di gruppo». - **Categoria dei campioni**: categoria predefinita di tutti i prodotti campione. Lasciala disattivata. Se ne scegli un'altra, i campioni esistenti vengono spostati lì. - **Reindirizza le pagine dei campioni**: attivo per impostazione predefinita. Un visitatore che arriva sulla pagina di un prodotto campione viene reindirizzato con un 301 al prodotto di origine. - **Conversione conteggiata su**: solo l'acquisto del prodotto campionato, oppure qualsiasi acquisto successivo. ### Limiti - **Massimo di campioni per carrello**: 0 = illimitato. - **Massimo di campioni per cliente e finestra**: tutti i prodotti campione insieme, 0 = illimitato. - **Finestra mobile**: in giorni, 30 per impostazione predefinita. Con 0, i limiti per cliente valgono per tutti gli ordini passati, senza limite di tempo. ### Follow-up automatico - **Attiva le email di follow-up**. - **Intervallo dopo l'ordine del campione**: in giorni, 14 per impostazione predefinita. - **Solo clienti iscritti alla newsletter**: attivalo se la tua base giuridica per le email commerciali è il consenso. - **Includi un buono sconto**: per ogni follow-up viene generato un buono nominativo monouso. - **Importo del buono**: in percentuale, 10 per impostazione predefinita. - **Validità del buono**: in giorni, 30 per impostazione predefinita. L'URL del cron è indicato in questa sezione e nella dashboard. ## Mostrare il pulsante con Creative Elements o un tema personalizzato Se la scheda prodotto è costruita con un page builder, gli hook nativi non sempre vengono visualizzati, o non dove vorresti. Il modulo fornisce un hook dedicato, `displayDfSamplesButton`. 1. Nelle impostazioni, scegli **Posizione del pulsante: Solo posizione personalizzata (displayDfSamplesButton)**. Il pulsante non viene più aggiunto agli hook nativi, così non compare due volte. 2. Con **Creative Elements**: nel modello della scheda prodotto, aggiungi il widget **Module** dove vuoi il pulsante, poi scegli il modulo DF Samples e l'hook `displayDfSamplesButton`. 3. In un **tema personalizzato**: aggiungi `{hook h='displayDfSamplesButton'}` al template della scheda prodotto, ad esempio `templates/catalog/product.tpl`. Ovunque sia posizionato, il pulsante segue la combinazione selezionata e si aggiorna quando il cliente la cambia. ## Prezzi e sconti di gruppo Il prezzo del campione è indipendente dal prodotto di origine: prezzi a scaglioni, prezzi specifici e quantità minima del prodotto di origine non si applicano. Solo una regola di prezzo del catalogo rivolta a tutti i prodotti senza distinzione si applicherebbe anche ai campioni. Lo sconto di un gruppo di clienti (**Clienti > Gruppi**, ad esempio -15 % per i rivenditori) si applica per impostazione predefinita a tutti i prodotti, campioni compresi. Con **Non applicare: i campioni mantengono il loro prezzo**, il modulo esclude i prodotti campione dallo sconto di ogni gruppo: i rivenditori pagano il prezzo fissato per il campione e lo sconto continua ad applicarsi al resto del catalogo. I gruppi creati in seguito sono gestiti automaticamente. Il pulsante mostra il prezzo che pagherà il cliente connesso, con sconto di gruppo e IVA inclusi. ## Limiti e controllo del carrello Le regole vengono verificate a ogni salvataggio del carrello, non solo al clic sul pulsante. Un'aggiunta tramite i pulsanti + e - della pagina carrello, un URL diretto, «Riordina» o l'unione dei carrelli al login passa dagli stessi controlli: 1. le righe di campioni disattivati vengono rimosse; 2. i duplicati vengono rimossi (stesso campione, o stessa combinazione in modalità variante); 3. la quantità di ogni riga torna a 1; 4. viene applicato il massimo per carrello; 5. vengono applicati il massimo per prodotto e il massimo globale per cliente nella finestra mobile. Quando una riga deve essere tolta, viene rimossa la più recente. Il cliente vede un messaggio nella pagina del carrello o dell'ordine. Gli ordini annullati, rimborsati o con errore di pagamento non contano per i limiti. I carrelli creati da un dipendente nel back-office non sono soggetti ai limiti. ## Configurare il cron I follow-up vengono inviati da un cron. Pianifica ogni ora l'URL indicato nelle impostazioni. Esempio di crontab: ``` 0 * * * * wget -q -O /dev/null "https://tuo-negozio.it/module/dfsamples/cron?token=TUO_TOKEN" ``` Ogni esecuzione elabora fino a 50 ordini e restituisce un riepilogo JSON: `processed`, `sent`, `skipped`, `waiting` e `retry`. ### Regole applicate dal cron - Una sola email per ordine, anche se contiene più campioni. Elenca i prodotti provati e contiene al massimo un buono. - Sono considerati solo i campioni non convertiti e senza follow-up, trascorso l'intervallo. - L'ordine del campione deve aver raggiunto uno stato pagato, spedito o consegnato. Un ordine ancora in attesa di pagamento viene ricontrollato più tardi e scartato se è ancora non pagato 60 giorni dopo la scadenza del follow-up. - Gli ordini annullati, rimborsati o con errore di pagamento vengono ignorati. - Un campione il cui prodotto è stato acquistato nello stesso ordine non riceve follow-up. - Con l'opzione newsletter attiva, i clienti non iscritti non ricevono follow-up. - Se l'invio non riesce, il modulo riprova nelle esecuzioni successive, al massimo tre volte e con almeno sei ore di intervallo. Il buono generato per un'email non partita viene eliminato. - Due esecuzioni simultanee non possono inviare la stessa email: ogni ordine viene riservato prima dell'elaborazione. ## Monitoraggio delle conversioni Alla convalida di un ordine che contiene un campione, il modulo registra il cliente, la sua email, il prodotto di origine, la combinazione, la lingua e il negozio. Quando questo cliente effettua un ordine successivo, i campioni corrispondenti vengono segnati come convertiti: - in modalità **prodotto** (predefinita): se l'ordine contiene il prodotto di cui ha ricevuto il campione; - in modalità **qualsiasi acquisto**: appena l'ordine contiene un prodotto reale. La conversione è conteggiata solo quando l'ordine di acquisto raggiunge uno stato convalidato (pagamento accettato, ad esempio). Un ordine pagato con bonifico viene quindi conteggiato alla ricezione del pagamento. Un acquisto nello stesso ordine del campione non è una conversione. ## Dashboard Il pannello sopra l'elenco dei prodotti mostra: - **Campioni ordinati**: numero di righe campione registrate; - **Conversioni**: numero di campioni seguiti da un acquisto, e tasso di conversione; - **Fatturato delle conversioni**: totale IVA inclusa degli ordini di conversione, convertito nella valuta predefinita; - **Follow-up in attesa**. L'elenco dei prodotti mostra anche, per prodotto, il numero di campioni ordinati, il numero di conversioni e se la modalità variante è attiva. ## Email di follow-up I modelli si trovano nella cartella `mails` del modulo, in francese, inglese, spagnolo, tedesco e italiano, in versione HTML e testo (`dfsamples_followup`). Per le altre lingue installate, il modello inglese viene copiato all'installazione: traducilo nella cartella `mails/` seguita dal codice della lingua, ad esempio `mails/nl/`. Variabili disponibili: - `{firstname}` e `{lastname}`; - `{product_name}`: il prodotto o i prodotti provati, separati da virgole; - `{product_link}`: link alla scheda del primo prodotto; - `{voucher_block}`: buono formattato per la versione HTML, vuoto se il buono è disattivato; - `{voucher_text}`: lo stesso contenuto per la versione testo; - `{shop_name}`. ## Buoni sconto Con l'opzione attiva, ogni follow-up crea una regola carrello di PrestaShop: - codice nel formato SMPL seguito da otto caratteri casuali; - riservato al destinatario, utilizzabile una sola volta; - sconto in percentuale, validità configurabile. I buoni sono elencati in **Catalogo > Sconti > Regole carrello**. ## Catalogo, sitemap e feed prodotti I prodotti campione hanno la visibilità «da nessuna parte» e si trovano nella categoria Campioni disattivata. Non compaiono negli elenchi, nella ricerca né nei blocchi in evidenza, e la loro pagina reindirizza al prodotto di origine. La maggior parte dei moduli di sitemap e feed ignora questi prodotti. Se il tuo li include, escludi nelle sue impostazioni la categoria Campioni o i riferimenti che iniziano con SMPL. ## Compatibilità con il checkout Il modulo non interviene nel processo d'ordine: un campione è una normale riga prodotto. Funziona con il checkout nativo e con i checkout in una pagina che riprendono i passaggi nativi di PrestaShop. Il messaggio di rimozione di un campione compare nelle pagine del carrello e dell'ordine. ## Disinstallazione La disinstallazione elimina le tabelle, le impostazioni e la scheda del modulo. I prodotti campione vengono **disattivati, non eliminati**, e la categoria Campioni viene mantenuta, affinché lo storico degli ordini resti coerente. Una reinstallazione riutilizza questa categoria. Puoi eliminare questi prodotti e la categoria manualmente se non ti servono più. ## Risoluzione dei problemi ### Il pulsante non compare nella scheda prodotto Verifica che il prodotto sia iscritto e attivo in **Catalogo > Campioni (DF)**. Poi cambia la posizione del pulsante: alcuni temi non visualizzano displayProductActions. Con un page builder, usa l'hook displayDfSamplesButton. ### Al posto del pulsante compare un messaggio «Hai raggiunto il limite di campioni per questo prodotto»: il cliente ha raggiunto il suo massimo nella finestra mobile. «Il carrello contiene già il massimo di N campioni per ordine»: è stato raggiunto il massimo per carrello. Regola i limiti se necessario. ### I prodotti campione non hanno immagine Capitava con i campioni creati dalla versione 1.0.0 su PrestaShop 9. Fai clic su **Risincronizza i campioni**: le immagini mancanti vengono aggiunte. ### Il prezzo mostrato non è quello atteso Il prezzo si inserisce IVA inclusa e viene convertito con la regola fiscale del prodotto di origine. Per un cliente di un gruppo scontato, controlla l'impostazione «Sconti per gruppo clienti sui campioni». Una regola di prezzo del catalogo globale si applica anche ai campioni. ### I follow-up non partono Apri l'URL del cron in un browser e leggi il riepilogo JSON. `enabled: false` significa che i follow-up sono disattivati. `waiting` conta gli ordini di campioni non ancora pagati. Controlla anche l'intervallo, l'opzione newsletter e la configurazione email del negozio (**Parametri avanzati > E-mail**). ### Un campione scompare dal carrello È il controllo del carrello: duplicato, massimo per carrello o limite del cliente raggiunto. Il cliente vede un messaggio nella pagina del carrello.