manifest / forms / evillage-smsform

EVILLAGE.PL - SMS Form (kupon rabatowy)

Formularz pobrania kuponu rabatowego wysyłanego SMS-em przez SMSAPI. Po wysłaniu kuponu wysyła e-mail z numerem vouchera (autonumer). Blok „SMS Kupon” lub shortcode [evillage_smsform]

by Rafał Skonieczka · github.com/rskonieczka/evillage-smsform

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/rskonieczka/evillage-smsform/archive/refs/heads/main.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/rskonieczka/evillage-smsform ↗

Wtyczka WordPress z formularzem, w którym klient podaje numer telefonu i dostaje kupon rabatowy SMS-em przez SMSAPI.pl. Po udanej wysyłce administrator dostaje e-mail z kolejnym numerem vouchera (np. EV-000123), a każde pobranie trafia do rejestru w bazie.


Wersja	1.7.1
Wymagany WordPress	6.0+
Wymagane PHP	8.0+
Bramka SMS	SMSAPI.pl (konto i token OAuth)
Obsługiwane numery	polskie numery komórkowe (+48)
Język interfejsu	polski
Autor	Rafał Skonieczka / EVILLAGE.PL

Spis treści

Funkcje
Wymagania
Instalacja
Szybki start
Wstawianie formularza
Panel ustawień
Znaczniki w treściach
Zabronione numery
Ścieżka klienta
Jak to działa po stronie serwera
Bezpieczeństwo i ochrona przed nadużyciami
Pomiar konwersji (Google Ads / GA4)
Dla programistów
Usługi zewnętrzne
Prywatność i RODO
Dane w bazie i odinstalowanie
Ograniczenia
FAQ / rozwiązywanie problemów
Struktura plików
Historia zmian
Licencja

Funkcje

Formularz jako blok „SMS Kupon” (edytor blokowy) lub shortcode [evillage_smsform].
Wysyłka SMS przez SMSAPI.pl (REST, OAuth Bearer) z automatycznym przełączeniem na zapasowy endpoint przy awarii.
Tryb testowy – SMSAPI waliduje żądanie, ale nie wysyła SMS-a i nie pobiera punktów (domyślnie włączony).
Kod kuponu unikalny (8 znaków bez mylących 0/O, 1/I, z prefiksem) albo stały dla wszystkich.
Numer vouchera z autonumeracji bazy – atomowy, bez duplikatów także przy równoległych żądaniach.
E-mail HTML do administratora po każdym wysłanym kuponie.
Rejestr voucherów w panelu: liczniki wysłanych / nieudanych i 50 ostatnich wpisów.
Ochrona: jeden kupon na numer, blokada numerów premium / infolinii / VoIP / stacjonarnych, limit prób z IP, honeypot, nonce odporny na cache strony, blokada równoległych wysyłek na ten sam numer.
Wszystkie teksty widoczne dla klienta edytowalne w panelu.
Tekst zgody wyświetlany przy checkboxie na stronie (domyślnie zaznaczonym); treść zgody nie jest dodawana do SMS-a.
15 gotowych zestawów kolorów (kontrast min. 4.5:1, WCAG AA), 8 kolorów do ręcznej zmiany, ikona nagłówka, zaokrąglenia, podgląd na żywo.
Dostępność: etykiety, aria-invalid, komunikaty błędów powiązane z polami, role="alert", przenoszenie fokusu na potwierdzenie.
Responsywny układ – w wąskim kontenerze (telefon, sidebar) przycisk przechodzi pod pole.
Zasoby (CSS/JS) ładowane tylko na stronach, na których jest formularz.

Wymagania

WordPress 6.0 lub nowszy, PHP 8.0 lub nowszy.
MySQL / MariaDB (wtyczka używa GET_LOCK() do blokady równoległych wysyłek).
Konto w SMSAPI.pl z doładowanymi punktami i tokenem OAuth z uprawnieniem do wysyłki SMS.
Działająca wysyłka poczty z WordPressa (wp_mail) – zalecana wtyczka SMTP, inaczej e-maile o voucherach mogą nie dochodzić.
Opcjonalnie: zarejestrowane w SMSAPI pole nadawcy (nazwa zamiast numeru).

Instalacja

Wgraj katalog evillage-smsform do wp-content/plugins/ albo zainstaluj archiwum ZIP przez Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
Włącz wtyczkę w Wtyczki. Aktywacja tworzy tabelę {prefix}evsms_vouchers i zapisuje domyślne ustawienia.
Przejdź do Ustawienia → SMS Kupon.

Po aktualizacji wtyczki bez ponownej aktywacji schemat tabeli aktualizuje się sam (porównanie evsms_db_version).

Szybki start

W SMSAPI wygeneruj token OAuth (Panel klienta → API → Tokeny API) z uprawnieniem do SMS.
Ustawienia → SMS Kupon → SMS: wklej token, ustaw treść SMS-a (np. {site}: Twoj kod rabatowy to {code}).
Kupon i ochrona: wybierz kod unikalny lub stały, prefiks kodu i numeru vouchera.
Powiadomienia: wpisz adres(y), na które ma przychodzić e-mail o pobranym voucherze.
Wstaw blok „SMS Kupon” na stronę i wyślij próbne zgłoszenie – w trybie testowym SMS nie wychodzi, ale voucher i e-mail są tworzone normalnie (e-mail ma adnotację o trybie testowym).
Gdy wszystko działa, wyłącz tryb testowy. Dopóki jest włączony, w panelu administratora widać ostrzeżenie.

Token poza bazą danych (zalecane)

Zamiast zapisywać token w ustawieniach, dodaj do wp-config.php:

define( 'EVSMS_SMSAPI_TOKEN', 'twoj-token-oauth' );

Stała ma pierwszeństwo przed polem w panelu, a panel pokazuje wtedy informację, że token pochodzi z wp-config.php.

Wstawianie formularza

Blok

W edytorze blokowym dodaj blok „SMS Kupon” (kategoria Widżety, słowa kluczowe: sms, kupon, rabat, voucher). W panelu bocznym możesz nadpisać tytuł, podtytuł, treść przycisku i kolor przycisku. Puste pola = wartości z panelu ustawień. Podgląd w edytorze jest renderowany po stronie serwera, więc wygląda jak na stronie.

Shortcode

[evillage_smsform]
[evillage_smsform title="Odbierz -10%" subtitle="Kod przyjdzie SMS-em" button="Wyślij kod" color="#e11d48"]

Atrybut	Opis
`title`	tytuł formularza
`subtitle`	podtytuł
`button`	treść przycisku
`color`	kolor przycisku i akcentów (HEX)
`layout`	`inline` – pole i przycisk obok siebie, `stacked` – w dwóch liniach, oba na 100% szerokości

Pominięty lub pusty atrybut = wartość z panelu ustawień. Na jednej stronie może być kilka formularzy.

Panel ustawień

Ustawienia → SMS Kupon (wymaga uprawnienia manage_options). Skrót „SMS Kupon” jest też dostępny w górnym pasku administratora WordPressa. Z listy wtyczek prowadzi tam również link „Ustawienia”.

Zakładka	Zawartość
SMS	token, pole nadawcy, tryb testowy, treść SMS z podglądem „dymka” i licznikiem znaków/części, zamiana polskich znaków (`normalize=1` – SMS mieści 160 znaków zamiast 70)
Kupon i ochrona	kod unikalny/stały, prefiks kodu, prefiks numeru vouchera, jeden kupon na numer, zabronione numery (gotowe grupy + własne początki), limit prób z jednego IP na godzinę
Komunikaty	wszystkie teksty dla klienta: tytuł, podtytuł, etykieta, treść przycisku (także w trakcie wysyłki), zgoda, ekran sukcesu, każdy komunikat błędu
Wygląd	15 zestawów kolorów, 8 kolorów do ręcznej zmiany, ikona nagłówka (10 wbudowanych, własny obrazek z biblioteki mediów albo brak), zaokrąglenie ramki oraz pól i przycisku (0–40 px), podgląd na żywo
Powiadomienia	adresy e-mail, temat e-maila
Konwersje	etykieta konwersji Google Ads, wartość, zdarzenie GA4, rozszerzone konwersje
Vouchery	liczniki wysłanych/nieudanych, statystyki konwersji, eksport CSV, 50 ostatnich voucherów (ze źródłem i statusem konwersji), usuwanie pojedynczych, zaznaczonych lub wszystkich rekordów
Dokumentacja	ten plik README wyświetlony w panelu (ze spisem treści)

Nad zakładkami jest pasek Pomoc z linkami: dokumentacja wtyczki, SMSAPI – tokeny API, pola nadawcy i dokumentacja API. Te same linki są przy polach token i pole nadawcy, a na liście wtyczek – link „Dokumentacja”.

Uwagi:

Puste pole komunikatu przywraca treść domyślną.
Puste pole tekstu zgody wyłącza checkbox zgody w formularzu.
Checkbox zgody jest domyślnie zaznaczony; można zmienić to ustawienie przy treści zgody w zakładce Komunikaty.
Puste pole koloru = kolor z palety motywu. Wtyczka korzysta ze zmiennych CSS motywu Blocksy (--theme-palette-color-*), a w innych motywach używa własnych kolorów zapasowych. Zestaw „Kolory motywu” czyści wszystkie kolory.
Limit prób z IP = 0 wyłącza limit.
Limit wszystkich SMS-ów (na godzinę i na dobę, ze wszystkich adresów IP łącznie) chroni punkty SMSAPI przed atakiem z wielu adresów. Po przekroczeniu formularz pokazuje komunikat „Wyczerpany limit wysyłek”, a na adres powiadomień idzie jeden alert na okno limitu. 0 wyłącza limit.
„Nie ujawniaj, że numer otrzymał już kupon” – przy powtórzonym numerze klient widzi zwykły ekran sukcesu, a SMS nie jest wysyłany. Nikt nie sprawdzi więc przez formularz, czy dany numer brał udział w promocji.

Ustawienia domyślne

Ustawienie	Wartość domyślna
Tryb testowy	włączony
Zamiana polskich znaków	włączona
Treść SMS	`{site}: Twoj kod rabatowy to {code}. Voucher nr {voucher}. Podaj kod przy zamowieniu.`
Domyślne zaznaczenie checkboxa zgody	włączone
Kod	unikalny, prefiks `RABAT-`
Prefiks vouchera	`EV-`
E-mail powiadomień	adres administratora witryny
Jeden kupon na numer	włączone
Zabronione numery	wszystkie grupy
Limit prób z IP	3 na godzinę
Limit wszystkich SMS-ów	30 na godzinę, 200 na dobę
Nie ujawniaj powtórzonego numeru	włączone
Zgodność z wyzwalaczami (Konwersje)	włączona

Znaczniki w treściach

Gdzie	Znaczniki
Treść SMS	`{code}` – kod kuponu, `{voucher}` – numer vouchera, `{site}` – nazwa witryny
Temat e-maila	`{code}`, `{voucher}`, `{site}`
Opis ekranu sukcesu	`{phone}` – zamaskowany numer, np. `+48 600 *** 200`
Błąd zabronionego numeru	`{prefix}` – dopasowany początek numeru, np. `70`

Zabronione numery

Domyślnie włączone są wszystkie grupy:

70x – numery o podwyższonej opłacie (700, 701, 703…),
80x – infolinie (800 bezpłatne, 801 wspólnych kosztów…),
39x – numery VoIP / nomadyczne,
numery stacjonarne – 49 stref numeracyjnych (12, 22, 32, 42, 58, 61, 71…), które nie odbierają SMS-ów.

Numery komórkowe (45, 50, 51, 53, 57, 60, 66, 69, 72, 73, 78, 79, 88) nie należą do żadnej grupy. Można dopisać własne początki numerów (bez +48). Blokada działa w przeglądarce (komunikat już podczas wpisywania) i na serwerze.

Ścieżka klienta

Pole z nieedytowalnym +48 i maską 600 100 200 (tylko cyfry; wklejone +48… / 0048… jest czyszczone).
Walidacja przy polu, błąd zabronionego początku numeru pojawia się już przy pisaniu.
Wysyłka: przycisk zmienia treść na „Wysyłanie…” ze spinnerem, zachowuje szerokość i blokuje podwójne kliknięcie.
Sukces: formularz zamienia się w potwierdzenie z zamaskowanym numerem.
Błędy pokazują się przy właściwym polu (telefon, zgoda) albo pod formularzem.
Zbyt szybka kolejna próba z tego samego urządzenia: przycisk jest zablokowany, a pod formularzem trwa odliczanie („Odczekaj 25 s…”).
Po odebraniu kuponu urządzenie od razu (także po odświeżeniu strony) widzi komunikat „kupon został już odebrany” zamiast formularza.
Obdarowanie: po wysłaniu kuponu, przy „urządzenie już odebrało” i przy „numer już otrzymał kupon” pojawia się zachęta „Chcesz obdarować kogoś kuponem? Wyślij mu link” z przyciskiem – na telefonie otwiera systemowe udostępnianie (Messenger, WhatsApp, SMS…), na komputerze kopiuje link do schowka.

Jak to działa po stronie serwera

Formularz pobiera świeży nonce przez AJAX (evsms_nonce), więc działa także na stronach z pamięci podręcznej (LiteSpeed Cache, WP Rocket itp.). Nonce jest pobierany zawczasu, gdy w polu jest już 9 cyfr (ważny w przeglądarce 30 minut), więc kliknięcie „Odbierz” wysyła od razu jedno żądanie. Wcześniej nie, bo evsms_nonce wydaje ciasteczko urządzenia i zużywa limit nowych urządzeń z IP.
Żądanie evsms_request przechodzi kontrole: nonce → honeypot → normalizacja numeru do 48XXXXXXXXX → zabronione początki → zgoda → limit prób z IP.
GET_LOCK na numer telefonu (brak podwójnej wysyłki), opcjonalnie sprawdzenie „jeden kupon na numer”.
Zapis wiersza pending – numer vouchera = AUTO_INCREMENT tabeli, formatowany jako prefiks + 6 cyfr.
POST https://api.smsapi.pl/sms.do (format=json, encoding=utf-8, skip_foreign=1, opcjonalnie normalize=1, from, test=1, idx + check_idx=1). Przy błędzie transportu lub odpowiedzi 5xx – ponowienie na https://api2.smsapi.pl/sms.do; dzięki idx SMSAPI nie wyśle drugiej wiadomości, jeśli pierwsza już wyszła.
Sukces → status sent i odpowiedź dla klienta. E-mail do administratora i akcja evsms_voucher_sent wykonują się po zamknięciu połączenia (litespeed_finish_request() na LiteSpeed, fastcgi_finish_request() na PHP-FPM), więc klient nie czeka na wysyłkę e-maila. Na innych serwerach zostają przed odpowiedzią. Żądanie ma ignore_user_abort(true) – zamknięcie karty nie przerwie zapisu po wysłaniu SMS-a. Błąd → status failed z opisem błędu (numer zostaje w rejestrze, więc luka w numeracji jest audytowalna), klient widzi komunikat „SMS nie został wysłany”.

Bezpieczeństwo i ochrona przed nadużyciami

Każdy wysłany SMS kosztuje, dlatego formularz ma kilka warstw ochrony:

nonce WordPressa dla każdego zgłoszenia,
honeypot – bot, który wypełni ukryte pole, dostaje fałszywy sukces, a SMS nie jest wysyłany,
ochrona przed floodem z jednego urządzenia – każda przeglądarka dostaje losowy identyfikator w podpisanym (HMAC) ciasteczku evsms_device (HttpOnly, SameSite=Lax); bez niego lub z podrobionym zgłoszenie jest odrzucane. Na nim działają: limit kuponów na urządzenie w okresie (domyślnie 1 na 30 dni), odstęp między próbami (30 s, z odliczaniem) i limit prób na godzinę (5). Jedno żądanie naraz z urządzenia (GET_LOCK),
limit nowych urządzeń z jednego IP (domyślnie 10/godz.) – kasowanie ciasteczek lub tryb incognito nie omija limitów w nieskończoność,
limit prób z jednego IP w oknie godzinowym (adres IP zapisywany jako HMAC-SHA256, nie jawnie),
jeden kupon na numer (liczą się tylko vouchery o statusie sent),
blokada numerów premium, infolinii, VoIP i stacjonarnych,
blokada MySQL na numer – dwa równoległe żądania na ten sam numer nie wyślą dwóch SMS-ów,
skip_foreign=1 – SMSAPI odrzuca numery zagraniczne,
wszystkie dane wyjściowe są escapowane, ustawienia sanityzowane, panel dostępny tylko dla manage_options.

Zalecenia: trzymaj token w wp-config.php, ustaw w SMSAPI limit dzienny / alert stanu konta, a przy dużym ruchu dodaj CAPTCHA lub ochronę typu WAF na admin-ajax.php.

Uwaga: za serwerem proxy / CDN (Cloudflare, load balancer) REMOTE_ADDR może być adresem proxy – wtedy limit z IP obejmuje wszystkich klientów naraz. Skonfiguruj serwer tak, żeby przekazywał prawdziwy adres klienta (np. mod_remoteip, real_ip w nginx).

Pomiar konwersji (Google Ads / GA4)

Konwersja jest zgłaszana dopiero po tym, jak SMSAPI przyjmie SMS z kuponem do wysłania (odpowiedź z id wiadomości). To nie jest raport doręczenia do telefonu – wtyczka go nie odbiera. Nie liczy się samo kliknięcie przycisku, błędny numer, duplikat (przy opcji „nie ujawniaj”) ani tryb testowy.

Dla zdarzenia witrynowego send_to utwórz w Google Ads konwersję witryny, np. z kategorią Przesłanie formularza kontaktowego. Import CSV z GCLID to odrębna konwersja typu Import z kliknięć. Zobacz: konfiguracja konwersji witryny i import konwersji z kliknięć.

Ustawienia → SMS Kupon → Konwersje: wpisz send_to konwersji Google Ads (AW-123456789/etykieta), opcjonalnie wartość i walutę oraz nazwę zdarzenia GA4.
Na stronie musi być tag gtag.js (np. z wtyczki Google Ads Multisite). Dla GTM do dataLayer trafia zawsze zdarzenie evsms_coupon_claimed z transaction_id.
transaction_id = numer vouchera, więc Google nie policzy tej samej konwersji dwa razy.
Rejestr zapisuje, że przeglądarka przekazała zdarzenie do warstwy tagowania (kolumna „Sygnał tagowania”). To nie jest potwierdzenie odebrania ani zarejestrowania konwersji przez Google Ads. Brak sygnału może wynikać m.in. z blokera lub braku zgody na cookies.
Przy każdym voucherze zapisywane są: strona, gclid, utm_source, utm_medium, utm_campaign (z sesji, więc także po przejściu na podstronę).
Zakładka Vouchery → Pobierz CSV daje plik z kolumnami Google Click ID, Conversion Name, Conversion Time (ze strefą z daty rekordu), Conversion Value, Conversion Currency, Order ID (tylko vouchery z gclid). W Google Ads potrzebna jest osobna konwersja typu „import z kliknięć”, a jej nazwę wpisz w ustawieniach (Nazwa konwersji do importu). Kolumn nie porównywałem z aktualnym szablonem Google – przed pierwszym importem sprawdź go w Google Ads.

Uwaga: wtyczka Google Ads Multisite pomija od tej wersji formularz .evsms-form w ogólnej konwersji „form” (inaczej każde kliknięcie liczyłoby się jako konwersja).

Zgodność z wyzwalaczami „Przesłanie formularza”

Formularz ma novalidate i wysyła dane przez AJAX, więc zwykłe zdarzenie submit powstaje przy każdym kliknięciu „Odbierz” – także przy pustym numerze. Wyzwalacz GTM „Przesłanie formularza” bez opcji „Sprawdź poprawność”, pomiar formularzy GA4 czy piksele liczyłyby wtedy każdą próbę jako konwersję.

Opcja Konwersje → Zgodność z wyzwalaczami (domyślnie włączona):

Skrypt inline w <head> (#evsms-tracking-guard) zatrzymuje kliknięcie „Odbierz” na window w fazie capture, zanim zobaczą je GTM i inne skrypty, i przekazuje je do obsługi formularza.
Po wysłaniu SMS-a (ta sama chwila co evsms_coupon_claimed) formularz emituje jedno zdarzenie submit, które istniejące wyzwalacze liczą jako konwersję. Nie ma go przy błędzie walidacji, duplikacie, limicie, awarii SMS ani w trybie testowym.
Przy GTM z opcją „Czekaj na tagi” wywołanie form.submit() dla emitowanego zdarzenia jest ignorowane, żeby strona się nie przeładowała.

Zalecany wyzwalacz w GTM to nadal zdarzenie niestandardowe evsms_coupon_claimed (z transaction_id). Wyłączenie opcji przywraca zwykłe zdarzenie submit przy każdym kliknięciu.

Opcja „Rozszerzone konwersje” przekazuje numer telefonu do Google (haszowany przez gtag) – włącz ją tylko, jeśli pozwala na to polityka prywatności i zgoda.

Dla programistów

Akcja `evsms_voucher_sent`

Wywoływana po udanym wysłaniu SMS-a i e-maila. Od wersji 1.7.1 – po wysłaniu odpowiedzi do przeglądarki (gdy serwer na to pozwala), więc wynik akcji nie trafia już do odpowiedzi AJAX. Dobre miejsce na integrację, np. utworzenie kuponu WooCommerce, zapis do CRM czy wysłanie zdarzenia do analityki.

/**
 * @param int    $id     Autonumer vouchera (ID wiersza).
 * @param string $number Sformatowany numer vouchera, np. EV-000123.
 * @param string $phone  Numer telefonu w formacie 48XXXXXXXXX.
 * @param string $code   Kod kuponu wysłany SMS-em.
 */
add_action( 'evsms_voucher_sent', function ( $id, $number, $phone, $code ) {
    // Przykład: kupon WooCommerce -10% na jedno użycie (dla trybu „kod unikalny”)
    if ( ! class_exists( 'WC_Coupon' ) || wc_get_coupon_id_by_code( $code ) ) {
        return;
    }
    $coupon = new WC_Coupon();
    $coupon->set_code( $code );
    $coupon->set_discount_type( 'percent' );
    $coupon->set_amount( 10 );
    $coupon->set_usage_limit( 1 );
    $coupon->set_description( 'Voucher ' . $number );
    $coupon->save();
}, 10, 4 );

Stałe

Stała	Opis
`EVSMS_SMSAPI_TOKEN`	token OAuth SMSAPI (w `wp-config.php`), ma pierwszeństwo przed ustawieniem w panelu

Endpointy AJAX

Akcja	Metoda	Opis
`evsms_nonce`	`admin-ajax.php`	zwraca świeży nonce (nagłówki `nocache`)
`evsms_conv`	`admin-ajax.php`, POST	zapis sygnału przekazania zdarzenia do warstwy tagowania (`id`, `token` z odpowiedzi `evsms_request`)
`evsms_request`	`admin-ajax.php`, POST	pola: `nonce`, `phone`, `consent`, `website` (honeypot); odpowiedź JSON `{ success, data: { message, meta \\| field } }`

Kody HTTP błędów: 400 – walidacja, 403 – nonce, 409 – trwa wysyłka na ten numer, 429 – limit prób.

Blok

Nazwa bloku: evillage/smsform (render po stronie serwera, atrybuty title, subtitle, button, color, layout).

Style

Wygląd opiera się na zmiennych CSS w klasie .evsms, więc można go nadpisać w motywie:

.evsms {
    --evsms-accent: #e11d48;
    --evsms-radius: 8px;
    --evsms-card-radius: 12px;
}

Dostępne zmienne: --evsms-accent, --evsms-on-accent, --evsms-text, --evsms-bg, --evsms-input-bg, --evsms-border, --evsms-error, --evsms-success, --evsms-radius, --evsms-card-radius.

Usługi zewnętrzne

Wtyczka łączy się z usługą zewnętrzną SMSAPI.pl (LINK Mobility Poland sp. z o.o.) wyłącznie w momencie, gdy klient wyśle formularz:

Co jest wysyłane: numer telefonu klienta, treść SMS-a (z kodem kuponu i numerem vouchera), opcjonalnie pole nadawcy oraz token API.
Dokąd: https://api.smsapi.pl/sms.do, zapasowo https://api2.smsapi.pl/sms.do.
Po co: dostarczenie kuponu SMS-em.
Regulamin: https://www.smsapi.pl/regulamin
Polityka prywatności: https://www.smsapi.pl/polityka-prywatnosci

Wtyczka nie wysyła żadnych innych danych na zewnątrz, nie ładuje zewnętrznych skryptów ani czcionek i nie zbiera statystyk.

Prywatność i RODO

Wtyczka przetwarza dane osobowe (numer telefonu). Administrator strony odpowiada za:

podstawę prawną i treść zgody (zakładka Komunikaty) – dostosuj ją do swojej polityki prywatności, możesz w niej wstawić link (dozwolony HTML),
informację w polityce prywatności, że numer telefonu jest przekazywany do SMSAPI.pl w celu wysyłki SMS-a,
umowę powierzenia przetwarzania danych z SMSAPI,
okres przechowywania danych w rejestrze voucherów.

Ciasteczko evsms_device jest techniczne (ochrona przed nadużyciami, losowy identyfikator bez danych osobowych) – opisz je w polityce cookies. W bazie zapisywany jest tylko jego skrót HMAC.

Co jest zapisywane w bazie: numer telefonu jawnie (potrzebny do blokady „jeden kupon na numer”), kod kuponu, status i identyfikator wysyłki SMSAPI, opis błędu, skrót HMAC adresu IP (bez możliwości odczytania adresu) i data. Numer telefonu trafia także do e-maila powiadomienia.

Wtyczka nie integruje się (jeszcze) z narzędziami eksportu / usuwania danych osobowych WordPressa. Administrator może usuwać pojedyncze lub wybrane rekordy, a także cały rejestr w zakładce Ustawienia → SMS Kupon → Vouchery; żądania dotyczące konkretnej osoby trzeba obsłużyć ręcznie, weryfikując jej dane.

Dane w bazie i odinstalowanie

Miejsce	Zawartość
tabela `{prefix}evsms_vouchers`	rejestr voucherów (`id`, `phone`, `code`, `status`, `sms_id`, `error`, `ip_hash`, `device_hash`, `page`, `gclid`, `utm_*`, `conv_at`, `created_at`)
opcja `evsms_db_version`	wersja schematu tabeli
opcja z ustawieniami wtyczki	wszystkie ustawienia z panelu
transienty `evsms_rl_*`	liczniki limitu prób z IP (wygasają po godzinie)
transienty `evsms_dv_`, `evsms_nd_`	liczniki prób z urządzenia i nowych urządzeń z IP (wygasają po godzinie)
ciasteczko `evsms_device` (przeglądarka)	losowy identyfikator urządzenia + podpis HMAC, ważne 1 rok

Usunięcie wtyczki (uninstall.php) kasuje ustawienia (razem z tokenem SMSAPI), opcję evsms_db_version i transienty evsms_*. Tabela voucherów zostaje – rejestr ma wartość księgową. Aby usunąć ją także, zrób to ręcznie, np. wp db query "DROP TABLE wp_evsms_vouchers". Ciasteczek evsms_device w przeglądarkach klientów nie da się usunąć po stronie serwera – wygasną same.

Ograniczenia

Tylko polskie numery komórkowe (+48); wysyłka zagraniczna jest celowo zablokowana.
Tylko bramka SMSAPI.pl.
Brak realizacji / unieważniania kuponu i integracji z WooCommerce „z pudełka” – można je dopiąć przez akcję evsms_voucher_sent.
Interfejs i komunikaty tylko po polsku (teksty dla klienta można zmienić w panelu); wtyczka nie ma jeszcze plików tłumaczeń.
Rejestr w panelu pokazuje 50 ostatnich voucherów (bez eksportu CSV i wyszukiwania).
Brak CAPTCHA – ochronę przed botami zapewniają honeypot, limit z IP i blokady numerów.

FAQ / rozwiązywanie problemów

SMS nie przychodzi, a formularz pokazuje sukces. Sprawdź, czy tryb testowy jest wyłączony – w trybie testowym SMSAPI nie wysyła wiadomości. Dopóki jest włączony, w panelu widać ostrzeżenie.

Klient widzi „Nie udało się wysłać SMS-a”. Szczegółowy błąd SMSAPI jest zapisany przy voucherze w zakładce Vouchery (np. brak punktów, błędny token, niezarejestrowane pole nadawcy).

„Sesja formularza wygasła”. Strona jest z cache, a żądanie admin-ajax.php?action=evsms_nonce jest blokowane lub cache'owane. Wyklucz admin-ajax.php z cache i z reguł firewalla.

Wysyłka trwa długo. W DevTools → Sieć kliknij żądanie admin-ajax.php (akcja evsms_request) → zakładka Czas (Timing). Nagłówek Server-Timing pokazuje: boot (start WordPressa), sms (odpowiedź SMSAPI), mail (e-mail i integracje – tylko gdy wysyłane przed odpowiedzią) i app (cała obsługa). Po 3 sekundach klient widzi komunikat „Dłuższe oczekiwanie” (zmienisz go w Komunikatach).

Wszyscy dostają „Zbyt wiele prób”. Serwer widzi adres proxy zamiast adresu klienta – zob. uwagę w sekcji Bezpieczeństwo albo zwiększ / wyłącz limit (0).

Klient widzi „Na tym urządzeniu kupon został już odebrany”. To limit kuponów na urządzenie (zakładka Kupon i ochrona → Ochrona urządzenia). Do testów zmień limit dni na 0 albo usuń ciasteczko evsms_device i wpis evsmsClaimedUntil z localStorage przeglądarki.

„Włącz obsługę plików cookie”. Przeglądarka blokuje ciasteczka albo admin-ajax.php?action=evsms_nonce jest cache'owane (wtedy nie ustawia ciasteczka) – wyklucz admin-ajax.php z cache.

Nie przychodzi e-mail o voucherze. Sprawdź adres w zakładce Powiadomienia i konfigurację poczty (zalecana wtyczka SMTP). Nieudana wysyłka jest zapisywana w logu błędów PHP.

Polskie znaki w SMS-ie. Z włączoną opcją „zamiana polskich znaków” jeden SMS mieści 160 znaków; bez niej – 70 (kodowanie Unicode). Licznik w panelu pokazuje liczbę części.

Struktura plików

evillage-smsform/
├── evillage-smsform.php        # nagłówek wtyczki, autoloader, aktywacja
├── includes/
│   ├── class-settings.php      # panel ustawień, wartości domyślne, sanityzacja
│   ├── class-form.php          # shortcode, blok, AJAX, wydawanie voucherów, e-mail
│   ├── class-smsapi.php        # klient SMSAPI.pl
│   ├── class-vouchers.php      # tabela i rejestr voucherów
│   ├── class-device.php        # identyfikator urządzenia, limity floodu z urządzenia
│   └── class-markdown.php      # README → HTML dla zakładki Dokumentacja
└── assets/
    ├── smsform.js / .css       # formularz na stronie
    ├── block.js                # blok „SMS Kupon”
    └── admin.js / .css         # panel ustawień i podgląd na żywo

Historia zmian

1.7.1

Krótsze oczekiwanie po kliknięciu „Odbierz”: nonce pobierany zawczasu po wpisaniu 9 cyfr, a e-mail do administratora i akcja evsms_voucher_sent wykonywane po wysłaniu odpowiedzi (LiteSpeed / PHP-FPM).
ignore_user_abort(true): zamknięcie karty nie przerywa zapisu po wysłaniu SMS-a.
Komunikat przy wysyłce dłuższej niż 3 s („Dłuższe oczekiwanie”, edytowalny w Komunikatach).
Nagłówek Server-Timing z czasem etapów żądania (WordPress, SMSAPI, e-mail, całość).

1.7.0

Zgodność z wyzwalaczami „Przesłanie formularza” (GTM, GA4, piksele): kliknięcie „Odbierz” nie jest już widoczne dla skryptów analitycznych, a jedno zdarzenie submit powstaje dopiero po wysłaniu SMS-a z kuponem. Pusty lub błędny numer, duplikat i limity nie liczą się już jako konwersja bez zmian w kontenerze GTM. Przełącznik w zakładce Konwersje (domyślnie włączony).

1.6.0

Układ „W dwóch liniach”: pole numeru, a pod nim przycisk, oba na 100% szerokości. Wybór w zakładce Wygląd (kafelki ze schematem, podgląd na żywo), w bloku (panel „Układ”) i atrybutem shortcode layout="stacked".

1.5.0

Dodano usuwanie pojedynczych voucherów, zaznaczonych rekordów z widocznej listy oraz całego rejestru; operacje wymagają uprawnień administratora i nonce WordPressa.
Dodano potwierdzenie przed usunięciem oraz komunikat o wyniku operacji. Usunięcie jest trwałe i znosi blokadę „jeden kupon na numer” dla usuniętych numerów.

1.4.1

Skrót „SMS Kupon” w górnym pasku administratora WordPressa dla użytkowników z uprawnieniem manage_options.
Doprecyzowanie, że status konwersji oznacza przekazanie zdarzenia do warstwy tagowania, a nie potwierdzenie odbioru przez Google Ads.

1.4.0

Pomiar konwersji Google Ads / GA4 / dataLayer po potwierdzonym wysłaniu SMS-a, z transaction_id = numer vouchera.
Zapis źródła (strona, gclid, UTM) i sygnału przekazania zdarzenia do warstwy tagowania; statystyki i eksport CSV do importu offline.
Formularz nie wywołuje już fałszywej konwersji „form” z wtyczki Google Ads Multisite.

1.3.0

Limit wszystkich SMS-ów na godzinę i dobę z alertem e-mail.
Limit prób z IP odporny na równoległe żądania (blokada MySQL).
Opcja ukrywania, że numer otrzymał już kupon.
Ochrona przed podwójnym SMS-em przy ponowieniu na zapasowym endpoincie (idx + check_idx w SMSAPI).
Ustawienia (z tokenem SMSAPI) nie są już wczytywane automatycznie przy każdym żądaniu (autoload wyłączony).
uninstall.php usuwa ustawienia i dane tymczasowe (tabela voucherów zostaje).
Ochrona przed floodem z jednego urządzenia + zachęta „wyślij link” (obdarowanie).

1.2.1

Aktualna wersja: blok i shortcode, wysyłka przez SMSAPI z zapasowym endpointem, rejestr voucherów z autonumeracją, e-mail do administratora, zabronione numery, 15 zestawów kolorów, ikona nagłówka, podgląd na żywo.

Licencja

GPLv2 lub nowsza – https://www.gnu.org/licenses/gpl-2.0.html.

EVILLAGE.PL - SMS Form (kupon rabatowy)

Install

Spis treści

Funkcje

Wymagania

Instalacja

Szybki start

Token poza bazą danych (zalecane)

Wstawianie formularza

Blok

Shortcode

Panel ustawień

Ustawienia domyślne

Znaczniki w treściach

Zabronione numery

Ścieżka klienta

Jak to działa po stronie serwera

Bezpieczeństwo i ochrona przed nadużyciami

Pomiar konwersji (Google Ads / GA4)

Zgodność z wyzwalaczami „Przesłanie formularza”

Dla programistów

Akcja evsms_voucher_sent

Stałe

Endpointy AJAX

Blok

Style

Usługi zewnętrzne

Prywatność i RODO

Dane w bazie i odinstalowanie

Ograniczenia

FAQ / rozwiązywanie problemów

Struktura plików

Historia zmian

1.7.1

1.7.0

1.6.0

1.5.0

1.4.1

1.4.0

1.3.0

1.2.1

Licencja

Akcja `evsms_voucher_sent`