Smart Loyalty Tiers — Documentation complète

Introduction

Smart Loyalty Tiers est un programme de fidélité complet pour WooCommerce. Contrairement à la plupart des plugins de fidélité qui se contentent d’un simple compteur de points sur les achats, Smart Loyalty Tiers propose 5 sources de gain distinctes, 4 tiers VIP progressifs avec des récompenses concrètes (frais de port à vie, accès anticipé aux nouveautés, support prioritaire), un système de badges de gamification, et la conversion des points en coupon WooCommerce one-shot.

Installation et activation

1. Téléchargez le fichier ZIP smart-loyalty-tiers.zip depuis votre espace client DataFirefly.
2. Dans WordPress, allez dans Extensions → Ajouter une extension → Téléverser une extension.
3. Sélectionnez le ZIP puis cliquez sur Installer maintenant.
4. Cliquez sur Activer.

À l’activation, le plugin crée automatiquement 9 tables en base (préfixe wp_slt_), seed les 4 tiers Bronze / Silver / Gold / Platinum, insère 10 badges d’accomplissement par défaut, ajoute l’endpoint loyalty à Mon compte WooCommerce, et planifie 2 tâches cron (expiration quotidienne, recalcul horaire des tiers).

Configuration en 3 minutes

Après activation, un nouveau menu Loyalty apparaît dans la sidebar admin avec 5 sous-pages : Dashboard, VIP Tiers, Membres, Badges, Réglages.

Étape 1 — Taux de gain (Loyalty → Réglages)

Ajustez les valeurs par défaut selon votre stratégie :

• Points par euro dépensé — défaut : 1 (soit 1 pt / 1 €)
• Points par avis produit — défaut : 50
• Points par parrainage — défaut : 500
• Points par inscription newsletter — défaut : 100
• Points par partage social — défaut : 25

Étape 2 — Conversion en coupon

• Taux de conversion — défaut : 100 points = 1 € de réduction
• Seuil minimum de conversion — défaut : 500 points
• Plafond du coupon — défaut : 30 % du sous-total panier

Étape 3 — Affichage et gamification

• Libellé des points — défaut : « points » (par exemple : « miles », « stars », « fireflies »)
• Gamification active — active l’overlay de célébration lors d’un passage de tier
• Notifications email — active les emails de passage de tier et de badge gagné

Les 4 tiers VIP

Chaque client est automatiquement placé dans un tier en fonction de son total de points cumulés à vie (points lifetime, indépendamment des dépenses en coupons). Les tiers seedés à l’activation :

• Bronze — 0 point, aucun bénéfice spécial, tier d’entrée
• Silver — 500 points cumulés, multiplicateur x1,25 sur les points d’achat, accès anticipé 12h
• Gold — 2 000 points cumulés, multiplicateur x1,5, frais de port offerts, support prioritaire, accès anticipé 24h
• Platinum — 5 000 points cumulés, multiplicateur x2, frais de port à vie, accès anticipé 48h, produits exclusifs, 500 points de bonus anniversaire

Depuis Loyalty → VIP Tiers, chaque tier est éditable en direct avec un sélecteur de couleur. Les bénéfices configurables :

• Multiplicateur de points (points_multiplier) — appliqué automatiquement sur tous les points gagnés sur les achats
• Frais de port offerts (free_shipping) — les rates WooCommerce sont mis à zéro au calcul du panier
• Accès anticipé en heures (early_access_hours) — dicte combien d’heures avant la date d’embargo d’un produit ce tier peut le voir et l’acheter
• Support prioritaire (priority_support) — ajoute un badge orange sur les commandes dans l’admin et un header X-Priority dans les emails transactionnels
• Bonus anniversaire (birthday_bonus) — points crédités automatiquement le jour de l’anniversaire du client (si renseigné dans son profil)
• Produits exclusifs (exclusive_products) — active la logique de filtrage par tier sur les produits marqués comme exclusifs

Les 5 sources de points

1. Achats (PurchaseAction)

Les points sont crédités lorsque la commande passe au statut terminée (woocommerce_order_status_completed). Le calcul :

points = subtotal HT × points_par_euro × multiplicateur_tier

Le système est idempotent : impossible de gagner deux fois sur la même commande, même si le statut oscille. Sur remboursement complet ou partiel, les points sont automatiquement reversés proportionnellement au montant remboursé.

2. Avis produits (ReviewAction)

Les points sont crédités à la publication d’un avis validé (comment_post ou transition_comment_status → approved). Une option « Vérifier que le client est acheteur » permet de limiter les gains aux avis de vrais acheteurs (protection anti-spam).

3. Parrainage (ReferralAction)

Chaque utilisateur reçoit un code de parrainage unique et un lien de partage. Le tracking se fait par cookie de 30 jours (durée configurable via slt_referral_cookie_days). Le parrain gagne ses points quand son filleul complète sa première commande. Un bonus de bienvenue optionnel est crédité au filleul.

4. Newsletter (NewsletterAction)

Deux modes de déclenchement :

• Case à cocher au checkout — automatiquement gérée si la case est cochée
• Hook public — do_action('slt_newsletter_subscribed', $user_id, $email) — appelez-le depuis Mailchimp, Brevo, MailPoet, Klaviyo ou n’importe quel système

Pour un formulaire natif, utilisez le shortcode [slt_newsletter_form].

5. Partages sociaux (SocialShareAction)

7 plateformes supportées via le shortcode [slt_share_buttons] : Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, Email. Chaque partage est enregistré avec un cap anti-abus :

• Maximum 5 partages par jour par utilisateur (configurable)
• Un même partage (utilisateur, plateforme, URL) ne compte qu’une fois

Les récompenses concrètes

Frais de port offerts à vie

Pour les tiers avec free_shipping: true, tous les package rates WooCommerce sont mis à zéro au calcul du panier. Aucun coupon à saisir, aucune manipulation. Une notice verte s’affiche automatiquement sur le panier : « ✨ Frais de port offerts — statut VIP ».

Accès anticipé aux nouveautés

Sur chaque produit, une metabox « Accès anticipé Loyalty » permet de définir une date d’embargo (_slt_embargo_until). Tant que la date n’est pas atteinte, le produit devient :

• Non achetable pour les tiers en dessous du seuil configuré (filtre woocommerce_is_purchasable)
• Invisible dans les listes (filtre woocommerce_product_query)

Les tiers avec early_access_hours > 0 peuvent voir et acheter le produit dans la fenêtre définie avant la levée publique de l’embargo. Un bandeau ambre sur la fiche produit informe les clients éligibles.

Support prioritaire

Pour les tiers avec priority_support: true, chaque commande passée par le client :

• Reçoit un badge « Priority » orange visible dans la liste des commandes admin (HPOS et legacy)
• Voit un header X-Priority: high injecté dans les emails transactionnels — utile pour filtrer dans votre helpdesk (Zendesk, Freshdesk, Help Scout, etc.)

Système de badges (gamification)

10 badges d’accomplissement sont seedés à l’activation :

• First Purchase — première commande
• Regular Customer — 5 commandes cumulées
• Power Buyer — 10 commandes cumulées
• Reviewer — premier avis publié
• Critic — 10 avis publiés
• Brand Ambassador — premier parrainage réussi
• Influencer — 5 parrainages réussis
• Social Butterfly — 10 partages sociaux
• Insider — inscription à la newsletter
• Big Spender — 1 000 € dépensés à vie

Depuis Loyalty → Badges, éditez les badges existants ou créez-en de nouveaux. Chaque badge a un critère JSON :

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // pour les triggers count-based
  "amount": 1000.00       // pour lifetime_spend (montant devise)
}

Un badge peut aussi accorder un bonus de points à son déblocage.

Conversion des points en coupon

Depuis Mon compte → Loyalty, le client saisit le nombre de points à convertir et clique sur « Générer coupon ». Le plugin :

1. Crée un objet WC_Coupon unique et one-shot
2. Limite le coupon à l’adresse email du client
3. Fixe une expiration à 30 jours
4. Déduit les points du solde et enregistre la transaction

Un plafond slt_max_redemption_percent (30 % par défaut) empêche le coupon de dépasser un pourcentage du sous-total panier — protection contre la dilution de marge.

Les 7 shortcodes frontend

[slt_balance]

Affiche le solde de points du client connecté. Attribut optionnel : label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Affiche le nom du tier actuel dans un badge coloré (couleur du tier).

[slt_tier_badge]

[slt_progress_bar]

Barre de progression animée vers le tier suivant, avec le nombre de points restants et un shimmer effect.

[slt_progress_bar]

[slt_tiers_table]

Tableau comparatif de tous les tiers avec leurs seuils et bénéfices — parfait pour une page « Programme fidélité ».

[slt_tiers_table]

[slt_referral_link]

Affiche le lien de parrainage unique du client + bouton copier + compteur de parrainages réussis.

[slt_referral_link]

[slt_share_buttons]

Boutons de partage social. Attributs :

• url — URL à partager (défaut : URL de la page courante)
• title — titre à partager (défaut : titre de la page)
• platforms — liste séparée par virgules (défaut : toutes)

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

[slt_newsletter_form]

Formulaire d’inscription à la newsletter avec crédit automatique des points à la souscription.

[slt_newsletter_form title="Rejoignez notre newsletter VIP"]

Espace client (Mon compte → Loyalty)

Un nouvel onglet Loyalty est automatiquement ajouté après le tableau de bord de Mon compte WooCommerce. Le client y retrouve :

• Un hero coloré selon la couleur de son tier avec son solde et son statut
• Sa barre de progression vers le tier suivant
• La liste de ses bénéfices actuels
• Le formulaire de conversion en coupon (si son solde dépasse le seuil minimum)
• La grille de tous les badges (gagnés en couleur, verrouillés en gris)
• Son historique complet de transactions (25 dernières entrées par défaut)

Dashboard admin (Loyalty → Dashboard)

Le dashboard admin affiche des stats sur les 30 derniers jours :

• Nombre total de membres et actifs sur 30 jours
• Points en circulation (somme des soldes actifs)
• Points gagnés et échangés sur 30 jours
• Parrainages complétés sur 30 jours
• Distribution des membres par tier (barres)
• Activité récente (20 dernières transactions tous membres confondus)

Depuis la page Membres, vous pouvez rechercher un client, voir son solde et son tier, et lui ajuster manuellement ses points (award ou déduct) via un modal AJAX avec justification.

Emails transactionnels

Deux emails HTML responsive sont envoyés automatiquement :

Tier upgrade

Envoyé au passage d’un nouveau tier. Contient :

• Un bandeau à la couleur du nouveau tier avec un trophée
• La liste des nouveaux bénéfices débloqués
• Un CTA vers l’espace Loyalty

Le template est surchargeable en le copiant dans votre-theme/smart-loyalty-tiers/emails/tier-upgrade.php.

Badge earned

Envoyé au déblocage d’un nouveau badge avec le nom, la description et l’éventuel bonus de points crédité.

Hooks développeur

Chaque action du plugin déclenche des hooks pour permettre l’extension sans toucher au code :

// Après crédit de points
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Après déduction de points
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Passage de tier
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Badge débloqué
do_action('slt_badge_awarded', $user_id, $badge);

// Parrainage réussi
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Inscription newsletter (à déclencher depuis votre intégration)
do_action('slt_newsletter_subscribed', $user_id, $email);

Compatibilité HPOS et blocs Cart / Checkout

Le plugin déclare automatiquement sa compatibilité HPOS via FeaturesUtil::declare_compatibility(). Toutes les lectures de commande passent par l’API CRUD WooCommerce (wc_get_order()) — aucune requête directe sur wp_posts.

La compatibilité avec les blocs Cart et Checkout est également déclarée. Les frais de port offerts s’appliquent dans les deux modes (classique et blocs).

Multilingue (Polylang et WPML)

Le plugin est entièrement traduisible via load_plugin_textdomain avec le textdomain smart-loyalty-tiers. Le français et l’anglais sont livrés, un fichier POT complet est inclus pour toute autre langue.

Pour les sites multilingues :

• Polylang Pro — les noms de tiers et de badges peuvent être traduits via l’interface Polylang String Translations
• WPML — les mêmes chaînes sont enregistrées avec WPML via icl_register_string

FAQ et dépannage

Un client ne voit pas ses points crédités après une commande

Vérifiez que la commande est bien en statut terminée (le plugin n’attribue pas de points sur « en cours » ou « en attente »). Si le statut est correct, allez dans Loyalty → Membres, recherchez le client, et vérifiez son historique.

Les frais de port ne sont pas offerts pour un client Gold

Vérifiez dans Loyalty → VIP Tiers que le bénéfice « Frais de port offerts » est bien coché sur le tier Gold. Videz aussi les caches de session WooCommerce (wc_clear_cart_cache()).

L’endpoint Mon compte → Loyalty renvoie une 404

Allez dans Réglages → Permaliens et cliquez sur « Enregistrer les modifications » pour flusher les rewrite rules. C’est nécessaire une seule fois après activation.

Le cron ne se déclenche pas

Sur les sites à faible trafic, WordPress cron peut être irrégulier. Configurez un vrai cron système pour appeler wp-cron.php toutes les 5 à 15 minutes, et désactivez le pseudo-cron dans wp-config.php :

define('DISABLE_WP_CRON', true);

Un client réclame des points suite à un remboursement complet

C’est le comportement normal : sur remboursement complet ou partiel, les points correspondants sont automatiquement déduits. Si le client insiste, vous pouvez lui recréditer manuellement les points via Loyalty → Membres → Adjust.

Comment désactiver l’expiration des points ?

Dans Loyalty → Réglages, mettez « Durée avant expiration » à 0 jours. Les points ne seront jamais purgés.