Smart Loyalty Tiers — Documentazione completa

Introduzione

Smart Loyalty Tiers è un programma fedeltà completo per WooCommerce. A differenza della maggior parte dei plugin di fedeltà che offrono solo un semplice contatore di punti sugli acquisti, Smart Loyalty Tiers include 5 fonti di guadagno distinte, 4 livelli VIP progressivi con ricompense concrete (spedizione gratuita a vita, accesso anticipato ai nuovi prodotti, supporto prioritario), un sistema di badge di gamification, e la conversione dei punti in coupon WooCommerce monouso.

Installazione e attivazione

1. Scarica il file ZIP smart-loyalty-tiers.zip dalla tua area cliente DataFirefly.
2. In WordPress, vai su Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona lo ZIP e clicca su Installa ora.
4. Clicca su Attiva.

All’attivazione, il plugin crea automaticamente 9 tabelle in database (prefisso wp_slt_), inserisce i 4 livelli Bronze / Silver / Gold / Platinum, inserisce 10 badge di traguardo predefiniti, aggiunge l’endpoint loyalty a Il mio account di WooCommerce, e pianifica 2 attività cron (scadenza giornaliera, ricalcolo orario dei livelli).

Configurazione in 3 minuti

Dopo l’attivazione, un nuovo menu Loyalty appare nella sidebar admin con 5 sottopagine: Dashboard, Livelli VIP, Membri, Badge, Impostazioni.

Passo 1 — Tassi di guadagno (Loyalty → Impostazioni)

Regola i valori predefiniti in base alla tua strategia:

• Punti per unità di valuta spesa — predefinito: 1 (1 pt / 1 unità)
• Punti per recensione prodotto — predefinito: 50
• Punti per referral — predefinito: 500
• Punti per iscrizione newsletter — predefinito: 100
• Punti per condivisione social — predefinito: 25

Passo 2 — Conversione in coupon

• Tasso di conversione — predefinito: 100 punti = 1 unità di sconto
• Soglia minima di riscatto — predefinito: 500 punti
• Limite del coupon — predefinito: 30 % del subtotale carrello

Passo 3 — Visualizzazione e gamification

• Etichetta punti — predefinito: «punti» (per esempio: «miglia», «stelle», «fireflies»)
• Gamification attiva — attiva l’overlay di celebrazione al passaggio di livello
• Notifiche email — attiva le email di passaggio livello e badge ottenuto

I 4 livelli VIP

Ogni cliente è automaticamente assegnato a un livello in base al suo totale di punti cumulativi a vita (indipendentemente dai riscatti). I livelli inizializzati:

• Bronze — 0 punti, nessun beneficio speciale, livello di ingresso
• Silver — 500 punti cumulativi, moltiplicatore x1,25 sui punti di acquisto, accesso anticipato 12h
• Gold — 2 000 punti cumulativi, moltiplicatore x1,5, spedizione gratuita, supporto prioritario, accesso anticipato 24h
• Platinum — 5 000 punti cumulativi, moltiplicatore x2, spedizione gratuita a vita, accesso anticipato 48h, prodotti esclusivi, 500 punti bonus compleanno

Da Loyalty → Livelli VIP, ogni livello è modificabile in diretta con un selettore di colore. I benefici configurabili:

• Moltiplicatore di punti (points_multiplier) — applicato automaticamente a tutti i punti guadagnati sugli acquisti
• Spedizione gratuita (free_shipping) — i package rates di WooCommerce vengono messi a zero al calcolo del carrello
• Accesso anticipato in ore (early_access_hours) — quante ore prima della data di embargo di un prodotto questo livello può vederlo e acquistarlo
• Supporto prioritario (priority_support) — aggiunge un badge arancione sugli ordini nell’admin e inietta un header X-Priority nelle email transazionali
• Bonus compleanno (birthday_bonus) — punti accreditati automaticamente il giorno del compleanno del cliente (se indicato nel profilo)
• Prodotti esclusivi (exclusive_products) — attiva il filtraggio per livello sui prodotti contrassegnati come esclusivi

Le 5 fonti di punti

1. Acquisti (PurchaseAction)

I punti vengono accreditati quando l’ordine passa allo stato completato (woocommerce_order_status_completed). Il calcolo:

punti = subtotale_iva_esclusa × punti_per_valuta × moltiplicatore_livello

Il sistema è idempotente: impossibile guadagnare due volte sullo stesso ordine, anche se lo stato oscilla. In caso di rimborso totale o parziale, i punti vengono automaticamente rovesciati in proporzione all’importo rimborsato.

2. Recensioni prodotti (ReviewAction)

I punti vengono accreditati quando viene pubblicata una recensione approvata (comment_post o transition_comment_status → approved). Un’opzione «Solo cliente verificato» permette di limitare i guadagni alle recensioni di veri acquirenti (protezione anti-spam).

3. Referral (ReferralAction)

Ogni utente riceve un codice referral univoco e un link di condivisione. Il tracking avviene tramite cookie di 30 giorni (configurabile via slt_referral_cookie_days). Il referrer guadagna i suoi punti quando il suo referral completa il suo primo ordine. Un bonus di benvenuto opzionale viene accreditato al referral.

4. Newsletter (NewsletterAction)

Due modalità di attivazione:

• Casella al checkout — gestita automaticamente se la casella è spuntata
• Hook pubblico — do_action('slt_newsletter_subscribed', $user_id, $email) — chiamalo da Mailchimp, Brevo, MailPoet, Klaviyo o qualsiasi altro sistema

Per un modulo nativo, usa lo shortcode [slt_newsletter_form].

5. Condivisioni social (SocialShareAction)

7 piattaforme supportate tramite lo shortcode [slt_share_buttons]: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, Email. Ogni condivisione è registrata con un limite anti-abuso:

• Massimo 5 condivisioni al giorno per utente (configurabile)
• Una stessa condivisione (utente, piattaforma, URL) conta una sola volta

Le ricompense concrete

Spedizione gratuita a vita

Per i livelli con free_shipping: true, tutti i package rates di WooCommerce vengono messi a zero al calcolo del carrello. Nessun coupon da reinserire, nessuna manipolazione. Un avviso verde viene automaticamente visualizzato nel carrello: «✨ Spedizione gratuita — stato VIP».

Accesso anticipato alle novità

Su ogni prodotto, una metabox «Accesso anticipato Loyalty» permette di definire una data di embargo (_slt_embargo_until). Finché la data non è raggiunta, il prodotto diventa:

• Non acquistabile per i livelli sotto la soglia configurata (filtro woocommerce_is_purchasable)
• Invisibile negli elenchi (filtro woocommerce_product_query)

I livelli con early_access_hours > 0 possono vedere e acquistare il prodotto nella finestra definita prima del rilascio pubblico dell’embargo. Un banner ambra sulla scheda prodotto informa i clienti idonei.

Supporto prioritario

Per i livelli con priority_support: true, ogni ordine effettuato dal cliente:

• Riceve un badge «Priority» arancione visibile nell’elenco ordini admin (HPOS e legacy)
• Riceve un header X-Priority: high iniettato nelle email transazionali — utile per filtrarle nel tuo helpdesk (Zendesk, Freshdesk, Help Scout, ecc.)

Sistema di badge (gamification)

10 badge di traguardo sono inizializzati all’attivazione:

• First Purchase — primo ordine
• Regular Customer — 5 ordini cumulati
• Power Buyer — 10 ordini cumulati
• Reviewer — prima recensione pubblicata
• Critic — 10 recensioni pubblicate
• Brand Ambassador — primo referral riuscito
• Influencer — 5 referral riusciti
• Social Butterfly — 10 condivisioni social
• Insider — iscrizione alla newsletter
• Big Spender — 1 000 unità spese a vita

Da Loyalty → Badge, modifica quelli esistenti o creane di nuovi. Ogni badge ha un criterio JSON:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // per trigger basati su contatore
  "amount": 1000.00       // per lifetime_spend (importo valuta)
}

Un badge può anche concedere un bonus di punti al suo sblocco.

Conversione dei punti in coupon

Da Il mio account → Loyalty, il cliente inserisce il numero di punti da convertire e clicca su «Genera coupon». Il plugin:

1. Crea un oggetto WC_Coupon unico e monouso
2. Limita il coupon all’indirizzo email del cliente
3. Fissa una scadenza a 30 giorni
4. Deduce i punti dal saldo e registra la transazione

Un limite slt_max_redemption_percent (30 % predefinito) impedisce che il coupon superi una percentuale del subtotale carrello — protezione contro la diluizione del margine.

I 7 shortcode frontend

[slt_balance]

Mostra il saldo punti del cliente collegato. Attributo opzionale: label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Mostra il nome del livello attuale in un badge colorato (colore del livello).

[slt_tier_badge]

[slt_progress_bar]

Barra di progresso animata verso il livello successivo, con il numero di punti rimanenti e un effetto shimmer.

[slt_progress_bar]

[slt_tiers_table]

Tabella comparativa di tutti i livelli con le loro soglie e benefici — perfetta per una pagina «Programma fedeltà».

[slt_tiers_table]

[slt_referral_link]

Mostra il link di referral univoco del cliente + pulsante copia + contatore di referral riusciti.

[slt_referral_link]

[slt_share_buttons]

Pulsanti di condivisione social. Attributi:

• url — URL da condividere (predefinito: URL della pagina corrente)
• title — titolo da condividere (predefinito: titolo della pagina)
• platforms — elenco separato da virgole (predefinito: tutte)

[slt_share_buttons platforms="facebook,twitter,whatsapp"]

[slt_newsletter_form]

Modulo di iscrizione alla newsletter con accredito automatico dei punti all’iscrizione.

[slt_newsletter_form title="Iscriviti alla nostra newsletter VIP"]

Area cliente (Il mio account → Loyalty)

Una nuova scheda Loyalty viene aggiunta automaticamente dopo la dashboard di Il mio account di WooCommerce. Il cliente vi trova:

• Un hero colorato in base al colore del suo livello, con il suo saldo e stato
• La sua barra di progresso verso il livello successivo
• L’elenco dei suoi benefici attuali
• Il modulo di conversione in coupon (se il suo saldo supera la soglia minima)
• La griglia di tutti i badge (guadagnati in colore, bloccati in grigio)
• La sua cronologia completa delle transazioni (ultimi 25 record predefiniti)

Dashboard admin (Loyalty → Dashboard)

La dashboard admin mostra statistiche a 30 giorni:

• Numero totale di membri e attivi in 30 giorni
• Punti in circolazione (somma dei saldi attivi)
• Punti guadagnati e riscattati in 30 giorni
• Referral completati in 30 giorni
• Distribuzione dei membri per livello (barre)
• Attività recente (ultime 20 transazioni di tutti i membri)

Dalla pagina Membri, puoi cercare un cliente, vedere il suo saldo e livello, e regolare manualmente i suoi punti (award o deduct) tramite un modale AJAX con giustificazione.

Email transazionali

Vengono inviate automaticamente due email HTML responsive:

Passaggio di livello

Inviata al raggiungimento di un nuovo livello. Contiene:

• Un banner con il colore del nuovo livello e un trofeo
• L’elenco dei nuovi benefici sbloccati
• Un CTA verso l’area Loyalty

Il template è sovrascrivibile copiandolo in tuo-tema/smart-loyalty-tiers/emails/tier-upgrade.php.

Badge ottenuto

Inviata allo sblocco di un nuovo badge, con nome, descrizione ed eventuale bonus di punti accreditato.

Hook per sviluppatori

Ogni azione del plugin attiva hook per permettere l’estensione senza toccare il codice:

// Dopo credito di punti
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Dopo deduzione di punti
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Cambio di livello
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Badge sbloccato
do_action('slt_badge_awarded', $user_id, $badge);

// Referral riuscito
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Iscrizione newsletter (attivarla dalla tua integrazione)
do_action('slt_newsletter_subscribed', $user_id, $email);

Compatibilità HPOS e blocchi Cart / Checkout

Il plugin dichiara automaticamente la sua compatibilità HPOS tramite FeaturesUtil::declare_compatibility(). Tutte le letture di ordini passano dall’API CRUD di WooCommerce (wc_get_order()) — nessuna query diretta su wp_posts.

La compatibilità con i blocchi Cart e Checkout è anch’essa dichiarata. La spedizione gratuita si applica in entrambe le modalità (classica e blocchi).

Multilingua (Polylang e WPML)

Il plugin è completamente traducibile tramite load_plugin_textdomain con il textdomain smart-loyalty-tiers. Francese e inglese sono inclusi, un file POT completo è incluso per qualsiasi altra lingua.

Per siti multilingua:

• Polylang Pro — i nomi di livelli e badge possono essere tradotti tramite l’interfaccia Polylang String Translations
• WPML — le stesse stringhe sono registrate con WPML tramite icl_register_string

FAQ e risoluzione problemi

Un cliente non vede i suoi punti accreditati dopo un ordine

Verifica che l’ordine sia nello stato completato (il plugin non attribuisce punti su «in elaborazione» o «in attesa»). Se lo stato è corretto, vai su Loyalty → Membri, cerca il cliente e verifica la sua cronologia.

La spedizione gratuita non viene applicata per un cliente Gold

Verifica su Loyalty → Livelli VIP che il beneficio «Spedizione gratuita» sia abilitato sul livello Gold. Svuota anche le cache di sessione di WooCommerce (wc_clear_cart_cache()).

L’endpoint Il mio account → Loyalty restituisce 404

Vai su Impostazioni → Permalink e clicca su «Salva modifiche» per aggiornare le rewrite rules. È necessario una sola volta dopo l’attivazione.

Il cron non si attiva

Su siti a basso traffico, il cron di WordPress può essere irregolare. Configura un vero cron di sistema per chiamare wp-cron.php ogni 5–15 minuti, e disabilita lo pseudo-cron in wp-config.php:

define('DISABLE_WP_CRON', true);

Un cliente reclama punti dopo un rimborso completo

È il comportamento normale: in caso di rimborso totale o parziale, i punti corrispondenti vengono automaticamente dedotti. Se il cliente insiste, puoi riaccreditargli manualmente i punti tramite Loyalty → Membri → Regola.

Come disattivare la scadenza dei punti?

In Loyalty → Impostazioni, imposta «Durata prima della scadenza» a 0 giorni. I punti non verranno mai eliminati.