# Smart Bundle Engine — Documentazione > Panoramica Smart Bundle Engine analizza lo storico dei tuoi ordini WooCommerce per rilevare i prodotti realmente acquistati insieme, genera automaticamente i bundle corrispondenti e li mostra sulla scheda prodotto, nel… - Pagina: - Lingua: it - Aggiornato il: 2026-07-01 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dfsmartbundle/index.md), [en](https://www.datafirefly.com/en/documentation/dfsmartbundle/index.md), [es](https://www.datafirefly.com/es/documentation/dfsmartbundle/index.md), [de](https://www.datafirefly.com/de/documentation/dfsmartbundle/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsmartbundle/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsmartbundle/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsmartbundle/index.md) - Indice: ## Panoramica Smart Bundle Engine analizza lo storico dei tuoi ordini WooCommerce per rilevare i prodotti realmente acquistati insieme, genera automaticamente i bundle corrispondenti e li mostra sulla scheda prodotto, nel carrello e nell'email post-acquisto — con un controllo del margine che limita automaticamente lo sconto se necessario. ## Installazione 1. Scarica il file `df-smart-bundle.zip` dal tuo account cliente DataFirefly. 2. Nella tua amministrazione WordPress, vai su **Plugin → Aggiungi nuovo → Carica plugin**. 3. Seleziona lo ZIP, clicca su **Installa ora** e attiva il plugin. 4. Un nuovo menu **Smart Bundles** appare nella barra laterale dell'amministrazione. **Requisiti:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+. La compatibilità HPOS (High-Performance Order Storage) è dichiarata nativamente. All'attivazione, il plugin crea 4 tabelle dedicate (`df_sbe_cooccurrence`, `df_sbe_bundles`, `df_sbe_bundle_items`, `df_sbe_analysis_state`) e pianifica il cron di analisi. ## Avvio rapido 1. Vai su **Smart Bundles → Analisi** e clicca su **Avvia l'analisi adesso**. 2. Al termine dell'analisi, la tabella **Affinità di acquisto principali** mostra le coppie rilevate con le loro metriche (occorrenze, confidenza, lift). 3. Se la generazione automatica è attiva (impostazione predefinita), i bundle vengono creati automaticamente — controllali in **Smart Bundles → Bundle**. 4. Visita una scheda prodotto interessata sul negozio: il blocco «Spesso acquistato insieme a» appare sotto il riepilogo del prodotto. **Suggerimento:** l'analisi ha bisogno di almeno alcune decine di ordini con più prodotti per produrre affinità sfruttabili. Se il tuo storico è ridotto, abbassa temporaneamente la soglia di co-occorrenze minime a 2 nelle impostazioni. ## Analisi di co-occorrenza Il motore percorre gli ordini **completati e in elaborazione** all'interno della finestra di analisi configurata (180 giorni per impostazione predefinita), a lotti di 200 ordini. Per ogni ordine con più prodotti, tutte le coppie vengono estratte e conteggiate. ### Le tre metriche - **Occorrenze** — numero di ordini contenenti la coppia A+B. - **Confidenza** — P(B|A) in percentuale: in quale percentuale degli ordini contenenti A troviamo anche B. Una confidenza di 20 significa che B appare nel 20 % degli ordini contenenti A. - **Lift** — rapporto tra la frequenza osservata della coppia e la frequenza attesa se A e B fossero indipendenti. Un lift superiore a 1 indica un'affinità reale; superiore a 2, un'affinità forte. ### Pianificazione L'analisi gira automaticamente via WP-Cron (hook `df_sbe_run_analysis`). Ogni esecuzione elabora fino a 25 lotti di 200 ordini e riprende al prossimo trigger grazie a un cursore persistente — nessun ordine viene elaborato due volte. Il pulsante **Reimposta stato** svuota le tabelle di analisi e riparte da zero. **Attenzione:** se WP-Cron è disattivato sul tuo server (`DISABLE_WP_CRON`), assicurati che un cron di sistema chiami `wp-cron.php` regolarmente, altrimenti l'analisi girerà solo con le esecuzioni manuali. ## Generazione automatica dei bundle Dopo ogni analisi completa, il motore seleziona le coppie che superano le tue soglie e crea i bundle corrispondenti. Tre impostazioni controllano la selezione: - **Co-occorrenze minime** (3 per impostazione predefinita) — numero minimo di ordini con la coppia. - **Confidenza minima** (10 % per impostazione predefinita) — soglia sotto la quale la coppia viene ignorata. - **Bundle max per prodotto** (3 per impostazione predefinita) — evita la sovrasaturazione di un prodotto. Le coppie selezionate sono classificate per punteggio (lift × occorrenze). I bundle creati automaticamente ricevono l'origine «Auto»; i bundle esistenti con gli stessi prodotti non vengono mai duplicati. I bundle manuali sono sempre conservati durante le rianalisi. ## Gestione dei bundle La schermata **Smart Bundles → Bundle** elenca tutti i bundle con i loro prodotti, sconto, margine minimo, contesti di visualizzazione, visualizzazioni e conversioni. Puoi filtrare per stato, origine (auto/manuale) o ricerca libera. ### Creare o modificare un bundle 1. Clicca su **Nuovo bundle** o **Modifica** su un bundle esistente. 2. Cerca e aggiungi i prodotti (minimo 2) — la quantità di ogni articolo è regolabile e l'ordine si riorganizza con trascina e rilascia. 3. Definisci lo sconto (percentuale o importo fisso) e il margine minimo. 4. Spunta i contesti di visualizzazione desiderati: scheda prodotto, carrello, email. 5. La **priorità** determina l'ordine di visualizzazione quando più bundle sono idonei (più alto = primo). Su un bundle esistente, una tabella di **Anteprima prezzi** mostra in tempo reale il subtotale, il costo stimato, lo sconto richiesto vs applicato, il prezzo finale e il margine reale. ## Controllo del margine Ogni bundle ha una soglia di **margine minimo** (in % del prezzo finale). Il motore calcola il prezzo minimo corrispondente: ``` prezzo_min_finale = costo_totale / (1 − margine_min / 100) ``` Se lo sconto richiesto spingerebbe il prezzo finale sotto questa soglia, viene **limitato automaticamente** allo sconto massimo compatibile. Lo sconto mostrato sul negozio è quindi sempre sicuro. ### Fonte del costo Il costo di ogni prodotto è determinato in questo ordine: 1. **Meta del prodotto** — la chiave `_df_cost_price` per impostazione predefinita, configurabile nelle impostazioni (compatibile con Cost of Goods e altri plugin di prezzo di costo). 2. **Rapporto di ripiego** — per i prodotti senza costo indicato, si assume una percentuale del prezzo di vendita (50 % per impostazione predefinita). **Suggerimento:** inserisci i costi reali prima sui tuoi prodotti più venduti — la limitazione del margine sarà così esatta sui bundle che contano di più. ## Visualizzazione sul negozio ### Scheda prodotto Il blocco si inserisce sull'hook `woocommerce_after_single_product_summary` con priorità configurabile (15 per impostazione predefinita, appena prima dei prodotti correlati). Mostra le miniature dei prodotti collegate da «+», il subtotale barrato, il prezzo del bundle e il pulsante di aggiunta con un clic. ### Carrello I suggerimenti appaiono sotto la tabella del carrello (`woocommerce_after_cart_table`). I bundle i cui prodotti sono già tutti nel carrello vengono nascosti automaticamente. ### Email post-acquisto Un blocco di suggerimento viene inserito nelle email **Ordine completato** e **Ordine in elaborazione** (solo lato cliente), in varianti HTML e testo semplice, con un link di ritorno diretto al negozio. Ogni contesto si attiva in modo indipendente e il suo titolo è personalizzabile nelle impostazioni. ## Applicazione dello sconto Il plugin non modifica mai i prezzi dei prodotti. Quando un bundle viene aggiunto al carrello, ogni articolo porta un marcatore interno; non appena tutti gli articoli del bundle sono presenti, lo sconto viene applicato come **fee negativa** WooCommerce («Sconto bundle»). Questo approccio: - preserva i prezzi di riga e i report di vendita; - resta compatibile con tasse, spedizioni e codici coupon; - rimuove automaticamente lo sconto se un articolo del bundle viene tolto dal carrello. ## Monitoraggio delle prestazioni Ogni visualizzazione di un bundle incrementa il suo contatore di **visualizzazioni**; ogni ordine contenente un bundle completo incrementa le sue **conversioni** (al passaggio allo stato «in elaborazione» o «completato», con protezione contro il doppio conteggio). Il tasso di conversione per bundle è mostrato nell'elenco dei bundle, e la schermata **Analisi** presenta le statistiche globali: ordini analizzati, coppie rilevate, bundle attivi, visualizzazioni e conversioni cumulative. ## Riferimento delle impostazioni ### Analisi di co-occorrenza - **Finestra di analisi (giorni)** — 180 per impostazione predefinita. Ordini completati e in elaborazione in questo periodo. - **Co-occorrenze minime** — 3 per impostazione predefinita. - **Confidenza minima (%)** — 10 per impostazione predefinita. - **Generazione automatica di bundle** — attiva per impostazione predefinita. - **Bundle max per prodotto** — 3 per impostazione predefinita. ### Prezzi e margine - **Sconto predefinito (%)** — 10, applicato ai bundle generati automaticamente. - **Margine minimo predefinito (%)** — 20. - **Chiave meta del prezzo di costo** — `_df_cost_price`. - **Rapporto di costo di ripiego (%)** — 50. ### Visualizzazione - **Contesti** — scheda prodotto / carrello / email, attivabili separatamente. - **Priorità hook scheda prodotto** — 15 per impostazione predefinita. - **Titoli** — un titolo personalizzabile per contesto. ## Multilingue Il plugin include 5 lingue (FR, EN, ES, DE, IT) in formato `.po`/`.mo` più un file `.pot` per le tue traduzioni (textdomain `df-smart-bundle`). Compatibile con Polylang e WPML — la lingua mostrata segue la locale del sito o dell'utente. ## Disinstallazione Disattivare il plugin rimuove solo il cron pianificato — i tuoi dati vengono conservati. **Eliminare** il plugin (via Plugin → Elimina) esegue `uninstall.php`, che rimuove definitivamente le 4 tabelle, tutte le opzioni e i metadati d'ordine creati dal plugin (compatibile HPOS). ## Risoluzione dei problemi ### Nessun bundle viene generato - Verifica che l'analisi sia stata eseguita: **Smart Bundles → Analisi** deve mostrare un numero di ordini analizzati superiore a zero. - Abbassa le soglie (co-occorrenze minime, confidenza minima) se il tuo storico è ridotto. - Verifica che la generazione automatica sia attiva nelle impostazioni. ### Il bundle non appare sul negozio - Il bundle deve essere **attivo** e il contesto interessato spuntato. - Un bundle il cui sconto calcolato è zero (limitazione totale del margine) viene nascosto sulla scheda prodotto. - Nel carrello, un bundle già completo viene nascosto per design. - Svuota la cache di pagina se usi un plugin di cache. ### Lo sconto applicato è inferiore a quello configurato È la limitazione del margine in azione: il costo totale del bundle non permette lo sconto richiesto senza scendere sotto il margine minimo. Verifica i costi dei prodotti o regola la soglia di margine del bundle. ## FAQ ### Il plugin funziona con i prodotti variabili? L'analisi e i bundle operano a livello del prodotto padre. Le variazioni di uno stesso prodotto vengono conteggiate insieme. ### Posso escludere alcuni prodotti dall'analisi? Non nella versione 1.0.0 — elimina o disattiva semplicemente i bundle indesiderati; non verranno ricreati se li elimini dopo aver disattivato la generazione automatica. ### I bundle sono compatibili con i coupon? Sì. Lo sconto del bundle è una fee negativa indipendente dai coupon WooCommerce; i due si cumulano. ### Qual è l'impatto sulle prestazioni? L'analisi gira in background a lotti. Sul negozio, le query dei bundle sono leggere (tabelle indicizzate) e gli asset si caricano solo sulle pagine prodotto e carrello.