Smart Loyalty Tiers: volledige documentatie

Inleiding

Smart Loyalty Tiers is een volwaardig loyaliteitsprogramma voor WooCommerce. Anders dan de meeste loyaliteitsplugins, die zich beperken tot een eenvoudige puntenteller op aankopen, biedt Smart Loyalty Tiers 5 verschillende bronnen om punten te verdienen, 4 oplopende VIP-niveaus met concrete voordelen (levenslang gratis verzending, vroege toegang tot nieuwigheden, voorrang bij de klantenservice), een systeem met gamificatiebadges, en het omzetten van punten in een eenmalige WooCommerce-coupon.

Installatie en activering

1. Download het ZIP-bestand smart-loyalty-tiers.zip vanuit uw DataFirefly-klantomgeving.
2. Ga in WordPress naar Plugins → Nieuwe plugin → Plugin uploaden.
3. Selecteer de ZIP en klik op Nu installeren.
4. Klik op Activeren.

Bij activering maakt de plugin automatisch 9 tabellen aan in de database (voorvoegsel wp_slt_), zet ze de 4 niveaus Bronze, Silver, Gold en Platinum klaar, voegt ze 10 standaardbadges toe, voegt ze het endpoint loyalty toe aan Mijn account in WooCommerce, en plant ze 2 crontaken in (dagelijkse verloopcontrole, herberekening van de niveaus per uur).

Configuratie in 3 minuten

Na de activering verschijnt een nieuw menu Loyalty in de beheerzijbalk, met 5 subpagina’s: Dashboard, VIP-niveaus, Leden, Badges en Instellingen.

Stap 1: verdiensttarieven (Loyalty → Instellingen)

Pas de standaardwaarden aan uw strategie aan:

• Punten per uitgegeven euro: standaard 1 (dus 1 punt per euro)
• Punten per productreview: standaard 50
• Punten per doorverwijzing: standaard 500
• Punten per nieuwsbriefinschrijving: standaard 100
• Punten per sociale deling: standaard 25

Stap 2: omzetten in een coupon

• Omrekenkoers: standaard 100 punten is 1 euro korting
• Minimumdrempel voor omzetting: standaard 500 punten
• Plafond van de coupon: standaard 30 procent van het subtotaal van de winkelwagen

Stap 3: weergave en gamificatie

• Benaming van de punten: standaard “punten” (bijvoorbeeld “miles”, “stars” of “fireflies”)
• Gamificatie actief: schakelt de feestelijke overlay in bij het bereiken van een nieuw niveau
• E-mailmeldingen: schakelt de e-mails bij een nieuw niveau en een behaalde badge in

De 4 VIP-niveaus

Elke klant wordt automatisch in een niveau geplaatst op basis van zijn levenslang opgebouwde puntentotaal (lifetime punten, los van wat hij aan coupons heeft besteed). De niveaus die bij de activering worden aangemaakt:

• Bronze: 0 punten, geen bijzondere voordelen, instapniveau
• Silver: 500 opgebouwde punten, vermenigvuldiger 1,25 op aankooppunten, 12 uur vroege toegang
• Gold: 2.000 opgebouwde punten, vermenigvuldiger 1,5, gratis verzending, voorrang bij de klantenservice, 24 uur vroege toegang
• Platinum: 5.000 opgebouwde punten, vermenigvuldiger 2, levenslang gratis verzending, 48 uur vroege toegang, exclusieve producten, 500 bonuspunten op de verjaardag

Via Loyalty → VIP-niveaus bewerkt u elk niveau meteen, met een kleurkiezer. De instelbare voordelen:

• Puntenvermenigvuldiger (points_multiplier): wordt automatisch toegepast op alle punten die met aankopen worden verdiend
• Gratis verzending (free_shipping): de WooCommerce-tarieven worden bij de winkelwagenberekening op nul gezet
• Vroege toegang in uren (early_access_hours): bepaalt hoeveel uur vóór de embargodatum van een product dit niveau het al kan zien en kopen
• Voorrang bij de klantenservice (priority_support): voegt een oranje badge toe aan de bestellingen in het beheer en een header X-Priority aan de transactionele e-mails
• Verjaardagsbonus (birthday_bonus): punten die automatisch worden bijgeschreven op de verjaardag van de klant (mits ingevuld in zijn profiel)
• Exclusieve producten (exclusive_products): schakelt de filtering per niveau in op producten die als exclusief zijn gemarkeerd

De 5 puntenbronnen

1. Aankopen (PurchaseAction)

De punten worden bijgeschreven wanneer de bestelling de status voltooid krijgt (woocommerce_order_status_completed). De berekening:

punten = subtotaal excl. btw × punten_per_euro × vermenigvuldiger_niveau

Het systeem is idempotent: het is onmogelijk twee keer punten te krijgen voor dezelfde bestelling, ook als de status heen en weer springt. Bij een volledige of gedeeltelijke terugbetaling worden de punten automatisch teruggeboekt, naar rato van het terugbetaalde bedrag.

2. Productreviews (ReviewAction)

De punten worden bijgeschreven bij het publiceren van een goedgekeurde review (comment_post of transition_comment_status → approved). Met de optie “Controleren of de klant heeft gekocht” beperkt u de punten tot reviews van echte kopers (antispambescherming).

3. Doorverwijzing (ReferralAction)

Elke gebruiker krijgt een unieke doorverwijscode en een deellink. Het volgen gebeurt met een cookie van 30 dagen (duur instelbaar via slt_referral_cookie_days). De doorverwijzer krijgt zijn punten wanneer de aangebrachte klant zijn eerste bestelling afrondt. Optioneel krijgt de aangebrachte klant een welkomstbonus.

4. Nieuwsbrief (NewsletterAction)

Er zijn twee manieren om dit te activeren:

• Selectievakje bij het afrekenen: wordt automatisch afgehandeld als het vakje is aangevinkt
• Publieke hook: do_action('slt_newsletter_subscribed', $user_id, $email), aan te roepen vanuit Mailchimp, Brevo, MailPoet, Klaviyo of welk systeem dan ook

Voor een ingebouwd formulier gebruikt u de shortcode [slt_newsletter_form].

5. Sociale delingen (SocialShareAction)

7 platformen worden ondersteund via de shortcode [slt_share_buttons]: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram en e-mail. Elke deling wordt vastgelegd met een limiet tegen misbruik:

• Maximaal 5 delingen per dag per gebruiker (instelbaar)
• Eenzelfde deling (gebruiker, platform, URL) telt maar één keer

De concrete voordelen

Levenslang gratis verzending

Voor niveaus met free_shipping: true worden alle WooCommerce-package rates bij de winkelwagenberekening op nul gezet. Er hoeft geen coupon te worden ingetypt en er is geen handeling nodig. Er verschijnt automatisch een groene melding op de winkelwagen: “✨ Gratis verzending, VIP-status”.

Vroege toegang tot nieuwigheden

Bij elk product laat een metabox “Vroege toegang Loyalty” u een embargodatum instellen (_slt_embargo_until). Zolang die datum niet is bereikt, is het product:

• Niet koopbaar voor niveaus onder de ingestelde drempel (filter woocommerce_is_purchasable)
• Onzichtbaar in de overzichten (filter woocommerce_product_query)

Niveaus met early_access_hours > 0 kunnen het product zien en kopen binnen het ingestelde venster vóór het embargo publiek wordt opgeheven. Een amberkleurige banner op de productpagina informeert de klanten die er recht op hebben.

Voorrang bij de klantenservice

Voor niveaus met priority_support: true krijgt elke bestelling van de klant:

• een oranje badge “Priority” die zichtbaar is in het besteloverzicht van het beheer (zowel HPOS als klassiek);
• een header X-Priority: high in de transactionele e-mails, handig om in uw helpdesk te filteren (Zendesk, Freshdesk, Help Scout en andere).

Badgesysteem (gamificatie)

Bij de activering worden 10 prestatiebadges aangemaakt:

• First Purchase: eerste bestelling
• Regular Customer: 5 bestellingen in totaal
• Power Buyer: 10 bestellingen in totaal
• Reviewer: eerste gepubliceerde review
• Critic: 10 gepubliceerde reviews
• Brand Ambassador: eerste geslaagde doorverwijzing
• Influencer: 5 geslaagde doorverwijzingen
• Social Butterfly: 10 sociale delingen
• Insider: inschrijving op de nieuwsbrief
• Big Spender: 1.000 euro levenslang uitgegeven

Via Loyalty → Badges bewerkt u bestaande badges of maakt u nieuwe aan. Elke badge heeft een criterium in JSON:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // voor triggers op aantal
  "amount": 1000.00       // voor lifetime_spend (bedrag in de valuta)
}

Een badge kan bij het behalen ook een puntenbonus toekennen.

Punten omzetten in een coupon

Via Mijn account → Loyalty vult de klant het aantal om te zetten punten in en klikt hij op “Coupon aanmaken”. De plugin:

1. maakt een uniek, eenmalig WC_Coupon-object aan;
2. beperkt de coupon tot het e-mailadres van de klant;
3. stelt een vervaldatum op 30 dagen in;
4. trekt de punten van het saldo af en legt de transactie vast.

Een plafond slt_max_redemption_percent (standaard 30 procent) verhindert dat de coupon een bepaald percentage van het winkelwagensubtotaal overschrijdt, als bescherming tegen margeverlies.

De 7 shortcodes aan de voorkant

[slt_balance]

Toont het puntensaldo van de ingelogde klant. Optioneel attribuut: label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Toont de naam van het huidige niveau in een gekleurde badge (de kleur van het niveau).

[slt_tier_badge]

[slt_progress_bar]

Geanimeerde voortgangsbalk naar het volgende niveau, met het aantal resterende punten en een shimmereffect.

[slt_progress_bar]

[slt_tiers_table]

Vergelijkingstabel van alle niveaus met hun drempels en voordelen, ideaal voor een pagina “Loyaliteitsprogramma”.

[slt_tiers_table]

[slt_referral_link]

Toont de unieke doorverwijslink van de klant, een kopieerknop en een teller van geslaagde doorverwijzingen.

[slt_referral_link]

[slt_share_buttons]

Knoppen om te delen op sociale media. Attributen:

• url: de te delen URL (standaard de URL van de huidige pagina)
• title: de te delen titel (standaard de paginatitel)
• platforms: lijst gescheiden door komma’s (standaard alle)

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

[slt_newsletter_form]

Inschrijfformulier voor de nieuwsbrief, met automatische puntentoekenning bij de inschrijving.

[slt_newsletter_form title="Word lid van onze VIP-nieuwsbrief"]

Klantomgeving (Mijn account → Loyalty)

Er wordt automatisch een nieuw tabblad Loyalty toegevoegd, na het dashboard van Mijn account in WooCommerce. De klant vindt daar:

• een gekleurde hero in de kleur van zijn niveau, met zijn saldo en status;
• zijn voortgangsbalk naar het volgende niveau;
• de lijst met zijn huidige voordelen;
• het formulier om punten in een coupon om te zetten (als zijn saldo boven de minimumdrempel ligt);
• het overzicht van alle badges (behaalde in kleur, vergrendelde in grijs);
• zijn volledige transactiehistoriek (standaard de 25 laatste regels).

Beheerdersdashboard (Loyalty → Dashboard)

Het beheerdersdashboard toont cijfers over de laatste 30 dagen:

• het totale aantal leden en het aantal actieve leden over 30 dagen;
• de punten in omloop (som van de actieve saldi);
• de punten die in 30 dagen zijn verdiend en ingewisseld;
• het aantal afgeronde doorverwijzingen over 30 dagen;
• de verdeling van de leden over de niveaus (balken);
• de recente activiteit (de 20 laatste transacties van alle leden samen).

Vanaf de pagina Leden kunt u een klant opzoeken, zijn saldo en niveau bekijken en zijn punten handmatig bijstellen (toekennen of aftrekken) via een AJAX-venster met een verantwoording.

Transactionele e-mails

Er worden automatisch twee responsieve HTML-e-mails verstuurd:

Niveau omhoog

Verstuurd bij het bereiken van een nieuw niveau. Bevat:

• een banner in de kleur van het nieuwe niveau, met een trofee;
• de lijst met de nieuw ontgrendelde voordelen;
• een oproep tot actie richting de Loyalty-omgeving.

Het template kunt u overschrijven door het te kopiëren naar uw-thema/smart-loyalty-tiers/emails/tier-upgrade.php.

Badge behaald

Verstuurd bij het ontgrendelen van een nieuwe badge, met de naam, de beschrijving en de eventueel bijgeschreven puntenbonus.

Hooks voor ontwikkelaars

Elke actie van de plugin stuurt hooks uit, zodat u kunt uitbreiden zonder de code aan te raken:

// Na het bijschrijven van punten
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Na het aftrekken van punten
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Niveauwijziging
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

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

// Geslaagde doorverwijzing
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Nieuwsbriefinschrijving (aan te roepen vanuit uw integratie)
do_action('slt_newsletter_subscribed', $user_id, $email);

Compatibiliteit met HPOS en de Cart- en Checkout-blokken

De plugin verklaart haar HPOS-compatibiliteit automatisch via FeaturesUtil::declare_compatibility(). Alle bestellingen worden gelezen via de CRUD-API van WooCommerce (wc_get_order()), zonder enige directe query op wp_posts.

Ook de compatibiliteit met de blokken Cart en Checkout is verklaard. De gratis verzending werkt in beide modi (klassiek en met blokken).

Meertaligheid (Polylang en WPML)

De plugin is volledig vertaalbaar via load_plugin_textdomain met het text domain smart-loyalty-tiers. Frans en Engels worden meegeleverd, en er is een volledig POT-bestand voor elke andere taal.

Voor meertalige sites:

• Polylang Pro: de namen van niveaus en badges zijn te vertalen via de String Translations van Polylang.
• WPML: dezelfde teksten worden bij WPML geregistreerd via icl_register_string.

Veelgestelde vragen en probleemoplossing

Een klant ziet zijn punten niet na een bestelling

Controleer of de bestelling wel de status voltooid heeft (de plugin kent geen punten toe bij “in behandeling” of “in afwachting”). Klopt de status, ga dan naar Loyalty → Leden, zoek de klant op en bekijk zijn historiek.

De verzending is niet gratis voor een Gold-klant

Controleer bij Loyalty → VIP-niveaus of het voordeel “Gratis verzending” wel is aangevinkt bij het niveau Gold. Leeg ook de sessiecaches van WooCommerce (wc_clear_cart_cache()).

Het endpoint Mijn account → Loyalty geeft een 404

Ga naar Instellingen → Permalinks en klik op “Wijzigingen opslaan” om de rewrite rules te flushen. Dat is één keer nodig, na de activering.

De cron gaat niet af

Op sites met weinig verkeer kan de WordPress-cron onregelmatig lopen. Stel een echte systeemcron in die wp-cron.php elke 5 tot 15 minuten aanroept, en schakel de pseudocron uit in wp-config.php:

define('DISABLE_WP_CRON', true);

Een klant klaagt over punten na een volledige terugbetaling

Dat is het normale gedrag: bij een volledige of gedeeltelijke terugbetaling worden de bijbehorende punten automatisch afgetrokken. Blijft de klant aandringen, dan kunt u de punten handmatig terugboeken via Loyalty → Leden → Bijstellen.

Hoe schakel ik het verlopen van punten uit?

Zet in Loyalty → Instellingen de “Termijn tot het verlopen” op 0 dagen. De punten worden dan nooit opgeruimd.