Smart Loyalty Tiers: kompletna dokumentacja

Wprowadzenie

Smart Loyalty Tiers to kompletny program lojalnościowy dla WooCommerce. W przeciwieństwie do większości wtyczek lojalnościowych, które ograniczają się do prostego licznika punktów za zakupy, Smart Loyalty Tiers oferuje 5 odrębnych źródeł punktów, 4 progresywne poziomy VIP z konkretnymi korzyściami (darmowa wysyłka dożywotnio, wcześniejszy dostęp do nowości, priorytetowe wsparcie), system odznak grywalizacyjnych oraz zamianę punktów na jednorazowy kupon WooCommerce.

Instalacja i aktywacja

1. Pobierz plik ZIP smart-loyalty-tiers.zip ze swojego konta klienta DataFirefly.
2. W WordPressie przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
3. Wybierz ZIP i kliknij Zainstaluj teraz.
4. Kliknij Włącz.

Przy aktywacji wtyczka automatycznie tworzy 9 tabel w bazie (przedrostek wp_slt_), zakłada 4 poziomy Bronze / Silver / Gold / Platinum, wstawia 10 domyślnych odznak osiągnięć, dodaje endpoint loyalty do Mojego konta WooCommerce i planuje 2 zadania cron (codzienne wygasanie, godzinne przeliczanie poziomów).

Konfiguracja w 3 minuty

Po aktywacji w pasku bocznym administracji pojawia się nowe menu Loyalty z 5 podstronami: Panel, Poziomy VIP, Członkowie, Odznaki, Ustawienia.

Krok 1: stawki naliczania (Loyalty → Ustawienia)

Dostosuj wartości domyślne do swojej strategii:

• Punkty za wydane euro: domyślnie 1 (czyli 1 pkt / 1 €)
• Punkty za opinię o produkcie: domyślnie 50
• Punkty za polecenie: domyślnie 500
• Punkty za zapis do newslettera: domyślnie 100
• Punkty za udostępnienie społecznościowe: domyślnie 25

Krok 2: zamiana na kupon

• Kurs wymiany: domyślnie 100 punktów = 1 € rabatu
• Minimalny próg wymiany: domyślnie 500 punktów
• Limit kuponu: domyślnie 30 % wartości koszyka

Krok 3: wyświetlanie i grywalizacja

• Etykieta punktów: domyślnie „punkty” (na przykład: „mile”, „gwiazdki”, „świetliki”)
• Grywalizacja aktywna: włącza nakładkę z gratulacjami przy awansie na wyższy poziom
• Powiadomienia e-mail: włącza e-maile o awansie poziomu i o zdobytej odznace

4 poziomy VIP

Każdy klient jest automatycznie przypisywany do poziomu na podstawie sumy punktów zebranych dożywotnio (punkty lifetime, niezależnie od wydatków na kupony). Poziomy zakładane przy aktywacji:

• Bronze: 0 punktów, bez specjalnych korzyści, poziom wejściowy
• Silver: 500 punktów, mnożnik x1,25 punktów zakupowych, wcześniejszy dostęp 12 h
• Gold: 2 000 punktów, mnożnik x1,5, darmowa wysyłka, priorytetowe wsparcie, wcześniejszy dostęp 24 h
• Platinum: 5 000 punktów, mnożnik x2, darmowa wysyłka dożywotnio, wcześniejszy dostęp 48 h, produkty ekskluzywne, 500 punktów bonusu urodzinowego

W Loyalty → Poziomy VIP każdy poziom można edytować na żywo, z selektorem koloru. Konfigurowalne korzyści:

• Mnożnik punktów (points_multiplier): stosowany automatycznie do wszystkich punktów zdobytych za zakupy
• Darmowa wysyłka (free_shipping): stawki WooCommerce są zerowane przy obliczaniu koszyka
• Wcześniejszy dostęp w godzinach (early_access_hours): określa, na ile godzin przed datą embarga produktu dany poziom może go zobaczyć i kupić
• Priorytetowe wsparcie (priority_support): dodaje pomarańczową odznakę przy zamówieniach w panelu i nagłówek X-Priority w e-mailach transakcyjnych
• Bonus urodzinowy (birthday_bonus): punkty naliczane automatycznie w dniu urodzin klienta (jeśli uzupełnione w jego profilu)
• Produkty ekskluzywne (exclusive_products): włącza logikę filtrowania per poziom dla produktów oznaczonych jako ekskluzywne

5 źródeł punktów

1. Zakupy (PurchaseAction)

Punkty są naliczane, gdy zamówienie przechodzi w status zrealizowane (woocommerce_order_status_completed). Obliczenie:

punkty = wartość netto × punkty_za_euro × mnożnik_poziomu

System jest idempotentny: nie da się zdobyć punktów dwa razy za to samo zamówienie, nawet jeśli status oscyluje. Przy zwrocie całkowitym albo częściowym punkty są automatycznie cofane proporcjonalnie do zwróconej kwoty.

2. Opinie o produktach (ReviewAction)

Punkty naliczane są przy publikacji zatwierdzonej opinii (comment_post albo transition_comment_status → approved). Opcja „Weryfikuj, czy klient jest nabywcą” pozwala ograniczyć naliczanie do opinii rzeczywistych kupujących (ochrona przed spamem).

3. Polecenia (ReferralAction)

Każdy użytkownik otrzymuje unikalny kod polecający i link do udostępnienia. Śledzenie działa przez 30-dniowe ciasteczko (czas konfigurowalny przez slt_referral_cookie_days). Polecający zdobywa punkty, gdy poleceniona osoba sfinalizuje pierwsze zamówienie. Opcjonalny bonus powitalny naliczany jest osobie poleconej.

4. Newsletter (NewsletterAction)

Dwa tryby wyzwalania:

• Pole wyboru na checkoucie: obsługiwane automatycznie, jeśli pole jest zaznaczone
• Publiczny hook: do_action('slt_newsletter_subscribed', $user_id, $email), wywołaj go z Mailchimpa, Brevo, MailPoeta, Klaviyo albo dowolnego systemu

Dla natywnego formularza użyj shortcode’u [slt_newsletter_form].

5. Udostępnienia społecznościowe (SocialShareAction)

7 obsługiwanych platform przez shortcode [slt_share_buttons]: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, e-mail. Każde udostępnienie jest rejestrowane z limitem antynadużyciowym:

• Maksymalnie 5 udostępnień dziennie na użytkownika (konfigurowalne)
• To samo udostępnienie (użytkownik, platforma, URL) liczy się tylko raz

Konkretne korzyści

Darmowa wysyłka dożywotnio

Dla poziomów z free_shipping: true wszystkie package rates WooCommerce są zerowane przy obliczaniu koszyka. Żadnego kuponu do wpisania, żadnych zabiegów. Na koszyku automatycznie wyświetla się zielony komunikat: „✨ Wysyłka gratis, status VIP”.

Wcześniejszy dostęp do nowości

Przy każdym produkcie meta box „Wcześniejszy dostęp Loyalty” pozwala ustawić datę embarga (_slt_embargo_until). Dopóki data nie zostanie osiągnięta, produkt staje się:

• Niemożliwy do kupienia dla poziomów poniżej skonfigurowanego progu (filtr woocommerce_is_purchasable)
• Niewidoczny na listach (filtr woocommerce_product_query)

Poziomy z early_access_hours > 0 mogą zobaczyć i kupić produkt w zdefiniowanym oknie przed publicznym zniesieniem embarga. Bursztynowy baner na karcie produktu informuje uprawnionych klientów.

Priorytetowe wsparcie

Dla poziomów z priority_support: true każde zamówienie złożone przez klienta:

• Otrzymuje pomarańczową odznakę „Priority” widoczną na liście zamówień w panelu (HPOS i legacy)
• Ma nagłówek X-Priority: high wstrzykiwany do e-maili transakcyjnych, przydatny do filtrowania w helpdesku (Zendesk, Freshdesk, Help Scout i innych)

System odznak (grywalizacja)

Przy aktywacji zakładanych jest 10 odznak osiągnięć:

• First Purchase: pierwsze zamówienie
• Regular Customer: 5 zamówień łącznie
• Power Buyer: 10 zamówień łącznie
• Reviewer: pierwsza opublikowana opinia
• Critic: 10 opublikowanych opinii
• Brand Ambassador: pierwsze udane polecenie
• Influencer: 5 udanych poleceń
• Social Butterfly: 10 udostępnień społecznościowych
• Insider: zapis do newslettera
• Big Spender: 1 000 € wydane dożywotnio

W Loyalty → Odznaki edytuj istniejące odznaki albo utwórz nowe. Każda odznaka ma kryterium w JSON:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // dla triggerów opartych na liczbie
  "amount": 1000.00       // dla lifetime_spend (kwota w walucie)
}

Odznaka może też przyznawać bonus punktowy przy odblokowaniu.

Zamiana punktów na kupon

W Moje konto → Loyalty klient wpisuje liczbę punktów do wymiany i klika „Generuj kupon”. Wtyczka:

1. Tworzy unikalny, jednorazowy obiekt WC_Coupon
2. Ogranicza kupon do adresu e-mail klienta
3. Ustawia wygaśnięcie na 30 dni
4. Odejmuje punkty od salda i zapisuje transakcję

Limit slt_max_redemption_percent (domyślnie 30 %) uniemożliwia przekroczenie przez kupon określonego procentu wartości koszyka, chroniąc marżę przed rozwodnieniem.

7 shortcode’ów frontendowych

[slt_balance]

Wyświetla saldo punktów zalogowanego klienta. Opcjonalny atrybut: label="mile".

[slt_balance label="świetliki"]

[slt_tier_badge]

Wyświetla nazwę bieżącego poziomu w kolorowej odznace (kolor poziomu).

[slt_tier_badge]

[slt_progress_bar]

Animowany pasek postępu do następnego poziomu, z liczbą brakujących punktów i efektem shimmer.

[slt_progress_bar]

[slt_tiers_table]

Tabela porównawcza wszystkich poziomów z progami i korzyściami, idealna na stronę „Program lojalnościowy”.

[slt_tiers_table]

[slt_referral_link]

Wyświetla unikalny link polecający klienta, przycisk kopiowania i licznik udanych poleceń.

[slt_referral_link]

[slt_share_buttons]

Przyciski udostępniania społecznościowego. Atrybuty:

• url: adres do udostępnienia (domyślnie adres bieżącej strony)
• title: tytuł do udostępnienia (domyślnie tytuł strony)
• platforms: lista rozdzielona przecinkami (domyślnie wszystkie)

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

[slt_newsletter_form]

Formularz zapisu do newslettera z automatycznym naliczeniem punktów przy subskrypcji.

[slt_newsletter_form title="Dołącz do naszego newslettera VIP"]

Strefa klienta (Moje konto → Loyalty)

Nowa zakładka Loyalty jest automatycznie dodawana po panelu Mojego konta WooCommerce. Klient znajdzie tam:

• Kolorowy hero w barwie swojego poziomu, z saldem i statusem
• Swój pasek postępu do następnego poziomu
• Listę bieżących korzyści
• Formularz zamiany na kupon (jeśli saldo przekracza minimalny próg)
• Siatkę wszystkich odznak (zdobyte w kolorze, zablokowane na szaro)
• Pełną historię transakcji (domyślnie 25 ostatnich wpisów)

Panel administracyjny (Loyalty → Panel)

Panel administracyjny pokazuje statystyki z ostatnich 30 dni:

• Łączna liczba członków i aktywnych w 30 dni
• Punkty w obiegu (suma aktywnych sald)
• Punkty zdobyte i wymienione w 30 dni
• Zrealizowane polecenia w 30 dni
• Rozkład członków według poziomów (słupki)
• Ostatnia aktywność (20 ostatnich transakcji wszystkich członków)

Na stronie Członkowie możesz wyszukać klienta, zobaczyć jego saldo i poziom oraz ręcznie skorygować punkty (dodać albo odjąć) przez modal AJAX z uzasadnieniem.

E-maile transakcyjne

Automatycznie wysyłane są dwa responsywne e-maile HTML:

Awans poziomu

Wysyłany przy przejściu na nowy poziom. Zawiera:

• Baner w kolorze nowego poziomu z trofeum
• Listę nowo odblokowanych korzyści
• CTA do strefy Loyalty

Szablon można nadpisać, kopiując go do twoj-motyw/smart-loyalty-tiers/emails/tier-upgrade.php.

Zdobyta odznaka

Wysyłany przy odblokowaniu nowej odznaki, z nazwą, opisem i ewentualnym naliczonym bonusem punktowym.

Hooki dla deweloperów

Każda akcja wtyczki wyzwala hooki pozwalające rozszerzać ją bez dotykania kodu:

// After points credited
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// After points deducted
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

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

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

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

// Newsletter subscription (trigger from your integration)
do_action('slt_newsletter_subscribed', $user_id, $email);

Zgodność z HPOS i blokami Cart / Checkout

Wtyczka automatycznie deklaruje zgodność z HPOS przez FeaturesUtil::declare_compatibility(). Wszystkie odczyty zamówień idą przez API CRUD WooCommerce (wc_get_order()), bez żadnych bezpośrednich zapytań do wp_posts.

Zadeklarowana jest też zgodność z blokami Cart i Checkout. Darmowa wysyłka działa w obu trybach (klasycznym i blokowym).

Wielojęzyczność (Polylang i WPML)

Wtyczka jest w pełni przetłumaczalna przez load_plugin_textdomain z domeną smart-loyalty-tiers. Francuski i angielski są dostarczane w komplecie, dołączony jest też pełny plik POT dla dowolnego innego języka.

Dla witryn wielojęzycznych:

• Polylang Pro: nazwy poziomów i odznak można tłumaczyć w interfejsie Polylang String Translations
• WPML: te same ciągi są rejestrowane w WPML przez icl_register_string

FAQ i rozwiązywanie problemów

Klient nie widzi punktów naliczonych po zamówieniu

Sprawdź, czy zamówienie ma status zrealizowane (wtyczka nie nalicza punktów przy „w trakcie realizacji” ani „oczekujące”). Jeśli status jest poprawny, przejdź do Loyalty → Członkowie, wyszukaj klienta i sprawdź jego historię.

Wysyłka nie jest darmowa dla klienta Gold

Sprawdź w Loyalty → Poziomy VIP, czy korzyść „Darmowa wysyłka” jest zaznaczona na poziomie Gold. Wyczyść też cache sesji WooCommerce (wc_clear_cart_cache()).

Endpoint Moje konto → Loyalty zwraca 404

Przejdź do Ustawienia → Bezpośrednie odnośniki i kliknij „Zapisz zmiany”, aby odświeżyć reguły przepisywania. To potrzebne tylko raz, po aktywacji.

Cron się nie uruchamia

W witrynach o niskim ruchu cron WordPressa bywa nieregularny. Skonfiguruj prawdziwy cron systemowy wywołujący wp-cron.php co 5 do 15 minut i wyłącz pseudo-cron w wp-config.php:

define('DISABLE_WP_CRON', true);

Klient reklamuje punkty po pełnym zwrocie

To zachowanie normalne: przy zwrocie całkowitym albo częściowym odpowiadające punkty są automatycznie odejmowane. Jeśli klient nalega, możesz ręcznie doliczyć mu punkty przez Loyalty → Członkowie → Koryguj.

Jak wyłączyć wygasanie punktów?

W Loyalty → Ustawienia ustaw „Czas do wygaśnięcia” na 0 dni. Punkty nigdy nie będą czyszczone.