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

- Strona: <https://www.datafirefly.com/pl/documentation/smart-loyalty-tiers/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/smart-loyalty-tiers/index.md), [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), [nl](https://www.datafirefly.com/nl/documentation/smart-loyalty-tiers/index.md), [pt](https://www.datafirefly.com/pt/documentation/smart-loyalty-tiers/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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

**Zgodność:** gotowe na HPOS, bloki Cart i Checkout, Polylang Pro i WPML, WordPress Multisite. Przetestowane do WooCommerce 9.5.

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

**Wymagania:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (zalecane 8.1+). Wtyczka odmawia aktywacji, jeśli WooCommerce nie jest zainstalowany i włączony.

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

Możesz dodać dowolną liczbę poziomów. Przeliczenie wykonuje się automatycznie przy każdym naliczeniu punktów, z godzinnym zabezpieczeniem przez cron dla zachowania spójności.

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

**Wsparcie:** w sprawach nieomówionych tutaj skontaktuj się z naszym priorytetowym wsparciem pod adresem [support@datafirefly.com](mailto:support@datafirefly.com). Odpowiedź w ciągu 24 godzin roboczych w trakcie roku wsparcia zawartego w cenie.