# DataFirefly Social Connect: kompletny przewodnik
> Kompletny przewodnik po instalacji, konfiguracji i użytkowaniu DataFirefly Social Connect: logowanie społecznościowe przez Google, Apple, Facebooka, Microsoft, LinkedIna i X dla WooCommerce, ze statystykami, przypisywaniem zamówień, testem A/B i antyfraudem.
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-social-connect/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-social-connect/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-social-connect/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-social-connect/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-social-connect/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-social-connect/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-social-connect/index.md)
- Indeks:
## Prezentacja
DataFirefly Social Connect dodaje do Twojego sklepu WooCommerce logowanie społecznościowe jednym kliknięciem przez sześciu dostawców (Google, Apple, Facebook, Microsoft, LinkedIn i X), kompletny panel statystyczny, przypisywanie zamówień do dostawcy pochodzenia, test A/B przycisków, system antyfraudowy i natywną zgodność z RODO.
Wtyczka nie używa żadnej zewnętrznej biblioteki z CDN: wykresy panelu są renderowane w natywnym canvasie HTML5, a przepływy OAuth 2.0 i OpenID Connect są zaimplementowane bezpośrednio w module (pełna weryfikacja podpisów JWKS dla Google One-Tap, podpis ES256 w locie dla Apple, wzmocnienie `appsecret_proof` dla Facebooka, PKCE S256 dla X).
**Wymagania**: WordPress 6.2 lub nowszy, WooCommerce 7.0 lub nowszy, PHP 8.0 lub nowszy. Zgodność z HPOS i blokami checkoutu WooCommerce jest deklarowana przez wtyczkę przy aktywacji.
## Instalacja
1. Pobierz plik ZIP wtyczki ze swojego konta klienta DataFirefly.
2. W WordPressie przejdź do _Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer_.
3. Wybierz plik ZIP i kliknij _Zainstaluj teraz_.
4. Kliknij _Włącz_. WooCommerce musi być aktywne w momencie aktywacji, inaczej wtyczka odmówi instalacji.
5. W pasku bocznym panelu pojawi się nowe menu _Social Connect_ z dwiema podstronami: _Statystyki_ i _Ustawienia_.
Przy aktywacji tworzone są dwie tabele SQL: `wp_dfsc_connections` (powiązane konta) i `wp_dfsc_events` (dziennik zdarzeń na potrzeby statystyk). Opcje domyślne zapisywane są w `dfsc_settings`.
## Konfiguracja dostawców
Każdy dostawca ma własną kartę w zakładce _Dostawcy_ w ustawieniach. Na górze każdej karty znajduje się **URI przekierowania** do skopiowania i wklejenia w konsoli dostawcy. To ten parametr pozwala Twojej witrynie odebrać powrót z uwierzytelnienia.
### Google (z One-Tap)
1. Wejdź na [Google Cloud Console](https://console.cloud.google.com/) i utwórz (albo wybierz) projekt.
2. W _APIs & Services → OAuth consent screen_ skonfiguruj ekran zgody (typ External dla sklepu publicznego, dodaj swoją domenę do domen autoryzowanych).
3. W _Credentials → Create credentials → OAuth client ID_ wybierz _Web application_.
4. W _Authorized redirect URIs_ wklej URI wyświetlone w karcie Google w Social Connect (postać: `https://twoja-domena.com/?dfsc_action=callback&dfsc_provider=google`).
5. Aby włączyć Google One-Tap, dodaj też swoją domenę główną w _Authorized JavaScript origins_.
6. Skopiuj _Client ID_ i _Client secret_ do odpowiednich pól karty Google, włącz przełącznik dostawcy i w razie potrzeby zaznacz _Pokazuj monit One-Tap niezalogowanym odwiedzającym_.
One-Tap działa z pełną weryfikacją podpisu JWKS i kontrolą claimów `aud`, `iss` i `exp`. Walidacja jest kryptograficzna, a nie tylko deklaratywna.
### Apple (Sign in with Apple)
1. Na [Apple Developer](https://developer.apple.com/) (wymagane płatne konto) przejdź do _Certificates, Identifiers & Profiles → Identifiers_.
2. Utwórz _App ID_ z włączoną funkcją _Sign In with Apple_.
3. Następnie utwórz _Services ID_ (to ten identyfikator posłuży jako „Client ID" po stronie Social Connect). Skonfiguruj jego Sign In with Apple: dodaj swoją domenę w _Domains_, a URI przekierowania z karty Apple w _Return URLs_.
4. Utwórz klucz prywatny (_Keys → +_) z zaznaczonym _Sign In with Apple_, powiązany z Twoim App ID. Pobierz plik `.p8` (można go pobrać tylko raz).
5. W karcie Apple wpisz _Services ID_, swój _Team ID_ (widoczny w prawym górnym rogu portalu), _Key ID_ (wyświetlany obok utworzonego klucza) i wklej pełną zawartość pliku `.p8` w pole _Klucz prywatny_ (razem z liniami `-----BEGIN PRIVATE KEY-----`).
Apple zwraca imię i nazwisko użytkownika tylko przy pierwszej zgodzie i nigdy nie udostępnia zdjęcia profilowego. Jeśli użytkownik włączy „Hide My Email", dostarczany jest adres przekaźnikowy Apple, którego wtyczka używa normalnie. Jeśli odmówi udostępnienia adresu, wtyczka generuje automatycznie adres techniczny.
### Facebook
1. Na [Meta for Developers](https://developers.facebook.com/) utwórz aplikację typu _Consumer_.
2. W aplikacji dodaj produkt _Facebook Login → Web_.
3. W ustawieniach Facebook Login dodaj URI przekierowania z karty Facebook w _Valid OAuth Redirect URIs_.
4. Pobierz _App ID_ i _App Secret_ z _Settings → Basic_ i wklej je do karty Facebook.
Wtyczka wzmacnia każde wywołanie Graph API parametrem `appsecret_proof` (HMAC-SHA256 tokena podpisany Twoim App Secret), zgodnie z dobrymi praktykami Meta.
### Microsoft
1. Na [Microsoft Entra (dawniej Azure AD)](https://entra.microsoft.com/) przejdź do _App registrations → New registration_.
2. Nadaj aplikacji nazwę. W _Supported account types_ wybierz _Accounts in any organizational directory and personal Microsoft accounts_, jeśli chcesz akceptować oba typy (używa tenanta `common`).
3. W _Redirect URI_ wybierz _Web_ i wklej URI z karty Microsoft.
4. Po utworzeniu skopiuj _Application (client) ID_ do odpowiedniego pola.
5. W _Certificates & secrets_ utwórz _New client secret_ i natychmiast skopiuj wartość (później nie będzie już widoczna) do pola _Client Secret_.
6. Zostaw pole _Tenant_ na `common`, aby akceptować konta firmowe i osobiste, albo wpisz identyfikator swojego tenanta, aby ograniczyć logowanie do jednej organizacji.
### LinkedIn
1. Na [LinkedIn Developers](https://www.linkedin.com/developers/) utwórz aplikację powiązaną ze stroną firmową.
2. W zakładce _Products_ poproś o aktywację _Sign In with LinkedIn using OpenID Connect_. Zatwierdzenie jest automatyczne.
3. W zakładce _Auth_ dodaj URI przekierowania z karty LinkedIn w _Authorized redirect URLs_.
4. Pobierz _Client ID_ i _Client Secret_ z zakładki _Auth_ i wklej je w Social Connect.
### X (Twitter)
1. Na [portalu deweloperskim X](https://developer.x.com/) utwórz projekt, a następnie aplikację.
2. W _User authentication settings_ włącz OAuth 2.0, wybierz typ _Confidential client_ (zalecany) i wklej URI przekierowania z karty X w _Callback URI / Redirect URL_.
3. Uzupełnij _Website URL_ (strona główna Twojego sklepu).
4. Pobierz _Client ID_ i _Client Secret_ i wklej je w Social Connect.
API X v2 nie zwraca adresu e-mail. Wtyczka generuje automatycznie adres techniczny, żeby utworzyć odpowiadające konto WordPressa. Jeśli zależy Ci na prawdziwym adresie, użytkownik może zawsze zaktualizować go w swoim panelu klienta.
## Rozmieszczenie i wygląd
W zakładce _Wygląd_ wybierasz, gdzie wyświetlać przyciski:
- **Formularz logowania** WooCommerce (strona Moje konto dla niezalogowanych).
- **Formularz rejestracji** WooCommerce.
- **Strona zamówienia (checkout)**, nad formularzem.
- **Panel Moje konto**, z listą powiązanych kont i przyciskami ręcznego wiązania.
Przyciski możesz też wstawić w dowolnym miejscu przez shortcode:
```
[datafirefly_social_connect]
[datafirefly_social_connect context="login" heading="yes" providers="google,apple"]
[datafirefly_social_connect context="custom" redirect="https://twoja-witryna/cel/"]
```
Wygląd jest konfigurowalny w czterech wymiarach:
- **Styl**: pełny (kolory marki), kontur (białe tło, kolorowa obwódka), minimalny (jasnoszare tło).
- **Kształt**: zaokrąglony, pigułka, kwadratowy.
- **Układ**: w kolumnie albo w wierszu.
- **Etykieta**: „Kontynuuj z…", „Zaloguj się przez…" albo sama ikona.
## Panel statystyczny
Panel (menu _Social Connect → Statystyki_) zbiera całą aktywność logowania społecznościowego w Twoim sklepie.
### KPI i wykresy
Selektor okresu w prawym górnym rogu: 7, 30, 90 lub 365 dni. Sześć wyświetlanych KPI obejmuje:
- **Logowania**: łączna liczba uwierzytelnień w okresie.
- **Rejestracje**: nowe konta utworzone przez logowanie społecznościowe.
- **Powiązane konta (łącznie)**: skumulowana liczba tożsamości społecznościowych powiązanych z użytkownikami.
- **Przypisane zamówienia** i **przypisany przychód**: patrz następna sekcja.
- **Współczynnik konwersji**: stosunek zamówień do logowań.
KPI uzupełniają cztery wykresy: krzywa zmian w czasie per dostawca, wykres kołowy podziału per dostawca, wykres kołowy podziału per typ urządzenia (komputer, telefon, tablet) oraz karta „Top kraje" zasilana geolokalizacją.
### Przypisywanie zamówień
Każde zamówienie WooCommerce złożone przez użytkownika, który trafił przez logowanie społecznościowe, jest przypisywane do jego dostawcy pochodzenia. Przypisanie opiera się na meta użytkownika `_dfsc_registered_via`, a awaryjnie na pierwszym aktywnym połączeniu społecznościowym użytkownika.
Nasłuchiwane są hooki `woocommerce_checkout_order_processed` i `woocommerce_store_api_checkout_order_processed`, co obejmuje zarówno klasyczny checkout, jak i checkout w blokach.
## Test A/B przycisków
W zakładce _Wygląd_ włącz blok _Test A/B przycisków_ i skonfiguruj wariant B (styl, kształt, układ, etykieta). Od tego momentu każdy odwiedzający losowo otrzymuje wariant A (Twoje ustawienia bazowe) albo wariant B (ciasteczko `dfsc_ab`, podział 50/50, przechowywane 30 dni).
Wyświetlenie liczone jest raz na sesję odwiedzającego (ciasteczko `dfsc_ab_imp`), żeby nie zawyżać wolumenu. Konwersje mierzone są na zdarzeniach logowania, rejestracji, wiązania kont i zamówienia, i raportowane na karcie _Test A/B_ panelu z wyświetleniami, konwersjami, przypisanymi zamówieniami, współczynnikami per wariant i automatycznym wskazaniem wariantu wygrywającego.
Aby wynik był statystycznie istotny, licz się z minimum 500 wyświetleniami na wariant. Poniżej 200 mierzone różnice to zasadniczo szum.
## Antyfraud: limit prób logowania
W zakładce _Prywatność_ możesz włączyć ograniczanie liczby prób per adres IP. Konfigurowalne są trzy progi:
- **Maksymalna liczba prób**: domyślnie 8.
- **Okno (minuty)**: domyślnie 5.
- **Czas blokady (minuty)**: domyślnie 15.
Po przekroczeniu limitu adres IP jest blokowany na skonfigurowany czas. Zdarzenie typu `blocked` trafia do dziennika i pojawia się w ostatniej aktywności. Ochrona obejmuje zarówno klasyczne przekierowania OAuth, jak i przepływ Google One-Tap.
Niezależnie od tego wtyczka utrzymuje listę domen jednorazowych adresów e-mail (Mailinator, Yopmail, 10MinuteMail i inne), które można blokować przy rejestracji. Listę rozszerza filtr `dfsc_disposable_domains`.
## Geolokalizacja
Włącz geolokalizację w zakładce _Prywatność_. Wtyczka korzysta z bazy MaxMind **już wbudowanej w WooCommerce**: nie jest wykonywane żadne wywołanie do usługi zewnętrznej. Jeśli geolokalizacja po stronie WooCommerce nie jest jeszcze włączona, przejdź do _WooCommerce → Ustawienia → Ogólne_ i włącz domyślną opcję geolokalizacji (WooCommerce pobierze bazę danych automatycznie).
Po włączeniu kraj każdego logowania jest rozwiązywany i zasila kartę _Top kraje_ panelu oraz kolumnę „Kraj" w eksporcie CSV.
## Eksport CSV
Przycisk _Eksportuj do CSV_ na górze panelu eksportuje wszystkie zdarzenia z wybranego okresu. Plik zawiera kolumnę dla każdego istotnego pola (data UTC, zdarzenie, dostawca, kontekst, kraj, urządzenie, wariant A/B, użytkownik, zamówienie, kwota, komunikat). Na początku pliku dodawany jest BOM UTF-8, dzięki czemu Excel i LibreOffice Calc poprawnie wyświetlają znaki diakrytyczne.
## Wiązanie kont
Współistnieją trzy mechanizmy wiązania tożsamości społecznościowej z kontem WordPressa:
1. **Tożsamość już znana**: użytkownik korzystał już z tego dostawcy, logowanie jest natychmiastowe.
2. **Automatyczne wiązanie po adresie e-mail**: istnieje już użytkownik WordPressa z tym samym adresem, który zwrócił dostawca. Jeśli adres jest zweryfikowany przez dostawcę (a opcja _Wymagany zweryfikowany e-mail_ jest włączona), wiązanie następuje automatycznie.
3. **Wiązanie ręczne**: z panelu _Moje konto_ zalogowany klient może powiązać lub odłączyć każdego dostawcę przez panel _Połączone konta_.
## RODO i prywatność
W zakładce _Prywatność_ dostępne są trzy tryby przechowywania adresów IP:
- **Haszowany** (domyślnie): HMAC-SHA256 z `wp_salt`, nieodwracalny.
- **Pełny**: adres IP jawnie (używaj tylko wtedy, gdy Twoja polityka prywatności wprost to przewiduje).
- **Brak**: adres IP w ogóle nie jest zapisywany.
Wtyczka rejestruje _exporter_ i _eraser_ w natywnym systemie RODO WordPressa (_Narzędzia → Eksport / Usuwanie danych osobowych_). Przy usunięciu użytkownika usuwane są też jego powiązane konta i zdarzenia (albo anonimizowane przy wymazywaniu danych).
## Shortcode i integracja zaawansowana
Shortcode `[datafirefly_social_connect]` przyjmuje następujące atrybuty:
- `context`: `login`, `register`, `checkout` albo `custom`.
- `heading`: `yes` albo `no`, wyświetla tytuł „Szybkie logowanie" nad przyciskami.
- `providers`: lista rozdzielona przecinkami ograniczająca wyświetlanie (np. `google,apple`).
- `redirect`: bezwzględny adres URL przekierowania po zalogowaniu (ma pierwszeństwo przed ustawieniem globalnym).
Renderowanie możesz też wywołać bezpośrednio w PHP:
```
echo do_shortcode('[datafirefly_social_connect context="custom" providers="google,microsoft"]');
```
## Hooki i filtry dla deweloperów
- `dfsc_disposable_domains` (filtr): rozszerza lub zastępuje listę domen jednorazowych adresów e-mail.
- `dfsc_user_registered` (akcja): wywoływana tuż po utworzeniu konta przez logowanie społecznościowe, z ID użytkownika i znormalizowanym profilem.
- `dfsc_after_login` (akcja): wywoływana po każdym udanym logowaniu.
- `dfsc_welcome_subject` i `dfsc_welcome_body` (filtry): personalizują temat i treść e-maila powitalnego.
- `dfsc_placeholder_email_domain` (filtr): zmienia domenę używaną dla adresów technicznych (odrzucone Apple Hide My Email, X).
API REST tylko do odczytu udostępnia zagregowane statystyki pod `/wp-json/datafirefly-social-connect/v1/stats?days=30` (wymagana zdolność `manage_woocommerce`). Włącz je w zakładce _Prywatność_.
## Zgodność
- **WooCommerce HPOS**: zgodność `custom_order_tables` jest deklarowana przy aktywacji, zamówienia w wydajnym magazynie są obsługiwane bez zastrzeżeń.
- **Bloki checkoutu**: hook `woocommerce_store_api_checkout_order_processed` jest nasłuchiwany równolegle z hookiem klasycznym, przypisywanie zamówień działa w obu typach checkoutu.
- **Polylang i WPML**: ciągi interfejsu są tłumaczalne przez dostarczony plik `.pot` (FR, EN, ES, DE, IT). Treści (e-mail powitalny i inne) są zgodne z obiema wtyczkami wielojęzycznymi.
- **Multisite**: każda witryna sieci ma własne tabele i opcje. Deinstalacja czyści każdą witrynę.
## Deinstalacja
Przy usuwaniu wtyczki z poziomu _Wtyczki_ automatycznie wykonywany jest plik `uninstall.php`. Usuwa on:
- Tabele `wp_dfsc_connections` i `wp_dfsc_events`.
- Opcje `dfsc_settings` i `dfsc_db_version`.
- Powiązane transienty (cache JWKS Google, cache sekretu klienta Apple, tokeny stanu).
- Metadane użytkowników (`_dfsc_provider`, `_dfsc_registered_via`, `_dfsc_avatar_id` i inne).
Twoi użytkownicy WordPressa i zamówienia WooCommerce nigdy nie są naruszane. W trybie multisite deinstalacja przechodzi przez wszystkie witryny sieci.
## FAQ i rozwiązywanie problemów
### Przycisk Google zwraca „redirect_uri_mismatch"
URI przekierowania wklejone w Google Cloud Console nie odpowiada dokładnie temu z karty Google w Social Connect. Sprawdź, czy skopiowano pełne URI (z `https://`, końcowym ukośnikiem i parametrami `?dfsc_action=callback&dfsc_provider=google`).
### Apple zwraca „invalid_client"
Trzy możliwe przyczyny: wpisany _Services ID_ to nie Services ID, tylko App ID, błędny _Team ID_, albo niekompletna zawartość klucza prywatnego `.p8` (brak linii `-----BEGIN PRIVATE KEY-----`). Zweryfikuj wszystkie trzy i wyczyść cache sekretu klienta Apple, zapisując ustawienia ponownie.
### Facebook zwraca błąd `appsecret_proof`
Wpisany App Secret jest błędny albo został zregenerowany po stronie Meta bez aktualizacji tutaj. Wejdź na Meta for Developers, skopiuj sekret ponownie i wklej go do karty Facebook.
### X / Twitter zwraca „invalid_request" przy powrocie
_Callback URI_ nie został poprawnie wpisany w portalu deweloperskim X, albo typ aplikacji to nie _Confidential client_, mimo że Client Secret jest wymagany. Zweryfikuj ustawienia w portalu.
### Panel jest pusty, choć były logowania
Sprawdź, czy wybrany okres obejmuje logowania (domyślnie 30 dni). Jeśli wtyczka została dopiero włączona, poczekaj na kilka zdarzeń, żeby wykresy zaczęły się wypełniać.
### Test A/B pokazuje współczynniki 0 %
Potrzebne jest minimum wyświetleń i konwersji, żeby współczynniki stały się miarodajne. Licz się z kilkuset wyświetleniami na wariant przed interpretacją wyników.
### Geolokalizacja nie zwraca żadnego kraju
Sprawdź, czy WooCommerce pobrało bazę MaxMind. Przejdź do _WooCommerce → Ustawienia → Ogólne_, włącz domyślną geolokalizację i odczekaj kilka minut. Bazę WooCommerce aktualizuje potem automatycznie.
### Jak wymusić odłączenie konta po stronie administratora?
Przejdź do tabeli `wp_dfsc_connections` i usuń odpowiedni wiersz. Przy następnym logowaniu przez tego dostawcę użytkownik zostanie potraktowany jako nowa tożsamość (powiązana z jego kontem WordPressa po adresie e-mail, jeśli automatyczne wiązanie jest aktywne).