# 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…

- Page: <https://www.datafirefly.com/documentation/smart-loyalty-tiers/>
- Langue: fr
- Mis à jour le: 2026-07-01
- Autres langues: [en](https://www.datafirefly.com/en/documentation/smart-loyalty-tiers/index.md), [es](https://www.datafirefly.com/es/documentation/smart-loyalty-tiers/index.md), [de](https://www.datafirefly.com/de/documentation/smart-loyalty-tiers/index.md), [it](https://www.datafirefly.com/it/documentation/smart-loyalty-tiers/index.md), [pl](https://www.datafirefly.com/pl/documentation/smart-loyalty-tiers/index.md), [nl](https://www.datafirefly.com/nl/documentation/smart-loyalty-tiers/index.md), [pt](https://www.datafirefly.com/pt/documentation/smart-loyalty-tiers/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

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

**Compatibilité :** HPOS-ready, blocs Cart & Checkout, Polylang Pro et WPML, WordPress Multisite. Testé jusqu'à WooCommerce 9.5.

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

**Prérequis :** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (8.1+ recommandé). Le plugin refuse de s'activer si WooCommerce n'est pas installé et actif.

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

Vous pouvez ajouter autant de tiers que vous voulez. Le recalcul se fait automatiquement à chaque gain de points, avec une sécurité horaire via cron pour garantir la cohérence.

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

**Support :** Pour toute question non couverte ici, contactez notre support prioritaire à [support@datafirefly.com](mailto:support@datafirefly.com). Réponse sous 24h ouvrées pendant votre année de support incluse.