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

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.

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.

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

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.