Logowanie przez Google, Apple i Facebook w PrestaShop: dokumentacja DataFirefly Social Connect

Prezentacja

DataFirefly Social Connect dodaje do PrestaShop 8 i 9 logowanie i rejestrację jednym kliknięciem przez Google, Apple i Facebook. Przyciski pojawiają się na stronie logowania, na stronie rejestracji oraz opcjonalnie w procesie zamówienia. Klient zarządza połączonymi kontami na stronie „Połączone konta” w swoim panelu klienta.

Moduł zawiera też pulpit statystyk (konwersja według usługi, urządzenia, godziny logowań, przychód), opcjonalny kupon powitalny i podpisany webhook dla Twojego CRM.

Ta dokumentacja dotyczy wersji 1.2.0. Moduł jest zgodny z PrestaShop od 8.0.0 do 9.x oraz z PHP od 7.4 do 8.5 (z PrestaShop 9 co najmniej PHP 8.1), z rozszerzeniami cURL i OpenSSL. Nie wymaga żadnych zależności Composera.

Instalacja

1. Pobierz archiwum modułu ze swojego konta klienta na datafirefly.com.
2. W panelu administracyjnym otwórz Moduły > Menedżer modułów > Załaduj moduł i wskaż plik ZIP.
3. Kliknij Zainstaluj. Moduł tworzy 5 tabel (ps_dfsc_identity, ps_dfsc_log, ps_dfsc_stats_daily, ps_dfsc_button_click, ps_dfsc_consent) i zapisuje ustawienia domyślne.
4. Kliknij Konfiguruj. Dopóki żadna usługa nie jest aktywna, moduł otwiera od razu zakładkę Usługi, a przyciski pozostają ukryte w sklepie.

Aktualizacja z wersji 1.0.0

Załaduj nowy plik ZIP w menedżerze modułów: aktualizacja uruchomi się automatycznie. Twoje dane uwierzytelniające, ustawienia, powiązania klientów i statystyki zostają zachowane. Aktualizacja poprawia indeksy tabeli powiązań, rejestruje nowe hooki, dodaje nowe ustawienia i usuwa ukrytą zakładkę administracyjną z wersji 1.0.0, która nie jest już potrzebna.

Po aktualizacji otwórz zakładkę Usługi i porównaj wyświetlone adresy powrotne z tymi, które zapisano w Google, Apple i Facebooku. Są one teraz zawsze tworzone w domyślnym języku sklepu. W sklepie wielojęzycznym, w którym panel administracyjny działał w innym języku, adres URI mógł się zmienić.

Aktualizacja do wersji 1.2.0

Załaduj plik ZIP 1.2.0 w menedżerze modułów: aktualizacja z wersji 1.0.0 lub 1.1.0 uruchamia się automatycznie, a powiązania klientów, ustawienia i statystyki zostają zachowane. Najważniejsze zmiany:

• Bezpieczeństwo Facebooka: e-mail przekazany przez Facebooka nie loguje już automatycznie istniejącego klienta, ponieważ Facebook nie informuje, czy adres został potwierdzony. Klient loguje się hasłem, a następnie łączy Facebooka na stronie Połączone konta. Nowa opcja pozwala przywrócić wcześniejsze działanie; domyślnie jest wyłączona, także po aktualizacji.
• Bezpieczeństwo Google: PKCE i weryfikacja tokenu ID (wystawca, odbiorca, ważność i nonce).
• Konta bez e-maila: konto założone przez Apple lub Facebooka bez adresu e-mail nie może już odłączyć swojej jedynej usługi, która jest jedynym sposobem logowania.
• RODO: powiązania i zgody klienta usuniętego z opcją „nie zezwalaj na ponowną rejestrację” są teraz również kasowane.
• Poprawki: pusty wykres „Logowania w czasie” po zmianie czasu na zimowy, ikona Facebooka, separator „lub” przeniesiony pod przyciski na stronie rejestracji i w procesie zamówienia, przetłumaczone zdarzenia w Ostatniej aktywności, style przycisków nie wpływają już na przyciski DF Simple Checkout.

Konfiguracja usług

Każda usługa wymaga danych uwierzytelniających utworzonych w jej konsoli deweloperskiej. Zakładka Usługi pokazuje dokładny adres powrotny do skopiowania do każdej konsoli: najmniejsza różnica powoduje błąd redirect_uri_mismatch.

Adresy te są tworzone w domyślnym języku sklepu i nie zmieniają się w zależności od języka odwiedzającego: wystarczy jeden URI na usługę. Klient wraca potem do swojego języka.

Usługa pojawia się w sklepie tylko wtedy, gdy jest włączona i ma uzupełnione wszystkie dane uwierzytelniające. Pasek na górze zakładki pokazuje dla każdej usługi, czy jest aktywny, niekompletny czy wyłączony.

Pola tajne (Klucz tajny klienta, Klucz tajny aplikacji, klucz prywatny Apple) nie są ponownie wyświetlane po zapisaniu. Pozostaw je puste, aby zachować bieżącą wartość.

Google

1. Otwórz Google Cloud Console, sekcję Dane logowania.
2. Utwórz lub wybierz projekt, a następnie kliknij Utwórz dane logowania > Identyfikator klienta OAuth, typ Aplikacja internetowa.
3. W polu Autoryzowane identyfikatory URI przekierowania wklej adres wyświetlony w module (postać: https://twoj-sklep.pl/pl/module/dfsocialconnect/callback?provider=google).
4. Wklej Identyfikator klienta (Client ID) i Klucz tajny klienta (Client secret) do modułu, włącz Google i zapisz.

Apple

1. Otwórz Apple Developer, Identifiers (wymagane płatne konto deweloperskie Apple).
2. Utwórz Services ID (a nie App ID). Jego identyfikator, na przykład com.twojsklep.signin, to Services ID, który wpisujesz w module.
3. Włącz Sign in with Apple dla tego Services ID, podaj domenę wyświetloną przez moduł oraz adres powrotny (provider=apple) jako Return URL.
4. W sekcji Keys utwórz klucz z włączonym Sign in with Apple i pobierz plik AuthKey_XXXXXXXXXX.p8. Apple pozwala pobrać go tylko raz.
5. Wpisz w module Services ID, Team ID (10 znaków, prawy górny róg konsoli Apple), Key ID (10 znaków) oraz całą zawartość pliku .p8 w polu Klucz prywatny (zawartość .p8), razem z liniami BEGIN i END.
6. Włącz Apple i zapisz. Moduł od razu sprawdza klucz i wyświetla „Zapisano prawidłowy klucz.” albo komunikat o błędzie.

Client_secret wymagany przez Apple to token JWT podpisany algorytmem ES256 Twoim kluczem .p8. Moduł generuje go przy każdym logowaniu z ważnością 5 minut: nie trzeba niczego ręcznie odnawiać.

Klienci, którzy ukrywają swój adres, otrzymują adres @privaterelay.appleid.com. Aby e-maile dotyczące zamówień do nich docierały, zarejestruj swoją domenę wysyłkową w usłudze Private Email Relay na koncie Apple Developer.

Apple odsyła klienta do sklepu żądaniem POST wysłanym z własnej witryny. Przeglądarki nie dołączają wtedy ciasteczka PrestaShop. Moduł wykrywa tę sytuację i ponawia żądanie z poziomu sklepu, dzięki czemu sesja i koszyk klienta zostają zachowane. Po Twojej stronie nie trzeba nic ustawiać.

Facebook

1. Otwórz Meta for Developers i utwórz aplikację.
2. Dodaj produkt Facebook Login i poproś o uprawnienie email.
3. W Facebook Login > Ustawienia wklej adres powrotny wyświetlony przez moduł (provider=facebook) w polu Prawidłowe identyfikatory URI przekierowania OAuth (Valid OAuth Redirect URIs).
4. Skopiuj App ID i App secret (Ustawienia > Podstawowe) do pól ID aplikacji i Klucz tajny aplikacji w module, włącz Facebook i zapisz.

Moduł korzysta z Facebook Graph API v23 i dodaje appsecret_proof do każdego wywołania: skradzionego tokenu dostępu nie da się użyć ponownie bez klucza tajnego Twojej aplikacji.

Facebook nie informuje, czy adres e-mail konta został potwierdzony. Dlatego domyślnie e-mail z Facebooka nigdy nie przypisuje usługi do istniejącego konta klienta: zob. opcję „Ufaj także adresom e-mail z Facebooka przy automatycznym powiązaniu” w zakładce Zachowanie.

Ścieżka klienta

Logowanie i zakładanie konta

Gdy klient wraca z Google, Apple lub Facebooka, moduł postępuje w tej kolejności:

1. Jeśli to konto społecznościowe jest już połączone z klientem sklepu, klient zostaje zalogowany.
2. Jeśli e-mail odpowiada istniejącemu klientowi i usługa go zweryfikowała i automatyczne łączenie jest włączone, usługa zostaje przypisana do tego konta, a klient zostaje zalogowany. W przypadku Facebooka e-mail uznaje się za zweryfikowany tylko wtedy, gdy włączona jest opcja „Ufaj także adresom e-mail z Facebooka przy automatycznym powiązaniu”.
3. Jeśli e-mail odpowiada istniejącemu klientowi, ale nie można go przypisać, konto nie jest tworzone. Klient widzi komunikat: Konto z tym adresem e-mail już istnieje. Zaloguj się hasłem, a następnie połącz tę usługę w sekcji „Połączone konta” na swoim koncie.
4. W pozostałych przypadkach powstaje konto z imieniem, nazwiskiem i adresem e-mail przekazanymi przez usługę, w języku, w którym klient przeglądał sklep, z losowym zaszyfrowanym hasłem.

Wyłączone konta nie mogą się zalogować. W multisklepie bez współdzielenia klientów konto społecznościowe nigdy nie zaloguje klienta innego sklepu.

Przy logowaniu moduł wywołuje natywne hooki actionAuthentication oraz, dla nowego konta, actionCustomerAccountAdd. Automatyczne reguły koszyka są przeliczane tak samo jak przy formularzu PrestaShop. Jeśli w PrestaShop włączona jest opcja e-maila potwierdzającego, nowy klient otrzymuje standardowy e-mail powitalny.

Powrót na stronę wyjścia

Po zalogowaniu klient wraca na stronę, z której wyszedł, na przykład do procesu zamówienia. W przeciwnym razie trafia na stronę wybraną w zakładce Zachowanie. Akceptowane są wyłącznie adresy Twojego sklepu: spreparowany link nie przekieruje klienta na inną witrynę.

Strona „Połączone konta”

Na stronie Moje konto pojawia się kafelek „Połączone konta” (motywy Classic i Hummingbird). Prowadzi on do strony z listą usług i ich stanem. Dla połączonej usługi strona pokazuje imię i nazwisko, e-mail, datę połączenia oraz awatar, jeśli został zaimportowany.

• Połącz: uruchamia logowanie w usłudze i przypisuje ją do konta klienta.
• Odłącz: usuwa powiązanie po potwierdzeniu. Jeśli to ostatnie połączone konto, klient dostaje prośbę, aby najpierw ustawić hasło przez „Nie pamiętasz hasła?” i zachować dostęp do konta. Konto utworzone bez adresu e-mail (Apple lub Facebook) nie może odłączyć swojej jedynej usługi: strona pokazuje „Jedyny sposób logowania”.

Zakładka Zachowanie

• Automatyczne łączenie przez zweryfikowany e-mail: przypisuje usługę do istniejącego konta, gdy dostawca potwierdził ten sam e-mail. Po wyłączeniu klient musi zalogować się hasłem, a potem połączyć usługę na swoim koncie. Domyślnie włączone.
• Ufaj także adresom e-mail z Facebooka przy automatycznym powiązaniu: domyślnie wyłączone. Facebook nie informuje, czy adres e-mail konta został potwierdzony: po włączeniu tej opcji konto na Facebooku z adresem e-mail jednego z Twoich klientów mogłoby zalogować się na jego konto klienta.
• Importuj awatar lokalnie: zapisuje zdjęcie profilowe w /img/dfsc/avatars/ (tylko HTTPS, maksymalnie 2 MB, sprawdzane formaty JPEG, PNG, GIF lub WebP) i wyświetla je na stronie Połączone konta.
• Zapisz nowe konta do newslettera: RODO wymaga wyraźnej zgody. Włącz tę opcję tylko wtedy, gdy zbierasz tę zgodę w inny sposób.
• Informacja prawna pod przyciskami: wybierz stronę CMS (regulamin lub politykę prywatności). Pod przyciskami wyświetla się zdanie „Kontynuując, akceptujesz: [strona]”, a akceptacja jest zapisywana dla każdego utworzonego konta. Wybierz „Brak”, aby ukryć informację.
• Kupon powitalny: dla każdego konta założonego przez usługę tworzy jednorazowy kupon ważny 90 dni, widoczny w koszyku klienta. Ustaw prefiks kodu (litery, cyfry, myślniki, maksymalnie 40 znaków) i kwotę brutto w walucie domyślnej. Kod ma postać WELCOME-GOOGLE-A1B2C3. Klient dostaje o nim informację zaraz po zalogowaniu.
• Grupy klientów według usługi: dodaje nowych klientów do wybranej grupy w zależności od użytej usługi.
• Maks. prób na adres IP (15 minut): liczba logowań uruchomionych z jednego adresu IP w ciągu 15 minut. Domyślnie 20, od 1 do 500.
• Strona po zalogowaniu: Moje konto, Strona główna, Proces zamówienia, Historia zamówień lub Dane osobowe. Używana, gdy klient nie przyszedł z konkretnej strony.
• Przechowuj logi i kliknięcia (dni): od 30 do 3650 dni, domyślnie 365. Logi zawierają adresy IP i są automatycznie usuwane raz dziennie. Dzienne statystyki pulpitu są zachowywane.
• Webhook wychodzący: adres URL i sekret, opis poniżej.

Zakładka Wygląd

• Styl przycisków: rounded (domyślny), pill, square, ghost lub minimal. Na dużym ekranie przyciski wyświetlają się obok siebie i przechodzą do nowej linii zamiast ucinać tekst.
• Treść przycisków: „Kontynuuj z”, „Zaloguj się przez” lub „Zarejestruj się przez”. Strona rejestracji zawsze używa „Zarejestruj się przez”.
• Pokaż przyciski także w procesie zamówienia: krok „Dane osobowe”, dla niezalogowanych odwiedzających. Domyślnie włączone.

Przyciski są zawsze wyświetlane na stronach logowania i rejestracji, gdy tylko co najmniej jedna usługa jest aktywna.

Pulpit

Pierwsza zakładka konfiguracji pokazuje statystyki z 7, 30, 90 lub 365 dni. W multisklepie uwzględnia sklep lub grupę wybraną w panelu administracyjnym.

• Wskaźniki: udane logowania, kliknięcia przycisków ze współczynnikiem konwersji, nowi klienci, niepowodzenia.
• Logowania w czasie, dzień po dniu i według usługi.
• Podział według usługi i współczynnik konwersji dla każdej usługi: nienaturalnie niski wskaźnik często oznacza źle skonfigurowaną usługę.
• Urządzenia i najczęstsze przeglądarki.
• Mapa dzień × godzina udanych logowań (czas serwera).
• Wskaźnik wykorzystania: odsetek aktywnych kont klientów połączonych z każdą usługą.
• Przychód od klientów logujących się społecznościowo: ważne zamówienia z okresu, brutto, w walucie każdego zamówienia. Każdy klient liczony jest raz, przy pierwszej połączonej usłudze.
• Ostatnia aktywność: 25 ostatnich zdarzeń (utworzenia kont, logowania, połączenia, odłączenia, niepowodzenia) z dokładnym błędem zwróconym przez dostawcę.

Webhook CRM

Moduł może wysyłać żądanie POST z treścią JSON na wybrany adres przy zdarzeniach identity.login (logowanie lub utworzenie konta), identity.linked (połączenie ze strony Połączone konta) i identity.unlinked (odłączenie). Wywołanie ma limit 3 sekund, aby nie spowalniać klienta. W razie niepowodzenia błąd trafia do logów PrestaShop.

Treść jest podpisywana HMAC-SHA256 sekretem webhooka. Losowy sekret jest generowany przy instalacji. Podpis jest wysyłany w nagłówku X-Dfsc-Signature w postaci sha256=<hex>, a nazwa zdarzenia w X-Dfsc-Event. Po stronie odbiorcy przelicz HMAC na surowej treści żądania i porównaj wynik.

{
  "event": "identity.login",
  "sent_at": "2026-10-14T11:27:45+02:00",
  "data": {
    "id_customer": 1234,
    "provider": "google",
    "event": "created",
    "email": "marie.dupont@example.com",
    "id_shop": 1
  }
}

Pole data.event przyjmuje wartość created (konto utworzone), linked (przypisane do istniejącego konta przez zweryfikowany e-mail) lub login (logowanie klienta, który ma już połączoną usługę).

RODO

• Informacja prawna pod przyciskami informuje klienta przed utworzeniem konta. Akceptacja jest zapisywana w ps_dfsc_consent razem ze stanem zapisu do newslettera.
• Logi i kliknięcia, które zawierają adresy IP, są usuwane po wybranym czasie.
• Klient może odłączyć każdą usługę na stronie Połączone konta.
• Z oficjalnym modułem psgdpr eksport danych klienta obejmuje jego połączone konta, a usunięcie jego danych kasuje powiązania, zgody i awatary.
• Gdy klient zostaje usunięty w panelu administracyjnym, także z opcją „nie zezwalaj na ponowną rejestrację”, jego powiązania, zgody i awatary są kasowane, a jego wpisy w logach anonimizowane.

Języki

Moduł jest dostarczany w językach angielskim, francuskim, hiszpańskim, niemieckim, włoskim, niderlandzkim, polskim i portugalskim, zarówno w sklepie, jak i w panelu administracyjnym. Teksty można zmienić w Międzynarodowy > Tłumaczenia > Tłumaczenia zainstalowanych modułów.

Odinstalowanie

Odinstalowanie z menedżera modułów usuwa 5 tabel ps_dfsc_*, swoje klucze konfiguracji DFSC_* (klucze DF Simple Checkout, który używa tego samego prefiksu, pozostają nienaruszone) oraz katalog /img/dfsc/ z zaimportowanymi awatarami. Konta klientów i ich zamówienia pozostają nienaruszone: kasowane są tylko powiązania społecznościowe.

Rozwiązywanie problemów

Zawsze zaczynaj od listy Ostatnia aktywność na pulpicie: pokazuje ona dokładny błąd zwrócony przez dostawcę.

redirect_uri_mismatch (Google) lub zablokowany adres URL (Facebook): URI zapisany u dostawcy nie odpowiada dokładnie temu, który wyświetla moduł. Sprawdź https, www, prefiks języka i parametr ?provider=.

invalid_client (Apple): błędny Team ID lub Key ID, niepełny klucz .p8, Services ID pomylony z App ID albo Return URL inny niż w module. Jeśli moduł wyświetla „Zapisanego klucza nie można odczytać: wklej go ponownie.”, wklej klucz jeszcze raz.

invalid_grant: kod autoryzacji wygasł lub został już użyty, na przykład po cofnięciu strony w przeglądarce. Wystarczy ponownie uruchomić logowanie.

„Sesja logowania wygasła. Spróbuj ponownie.”: na ekranie dostawcy minęło ponad 15 minut albo ciasteczko sklepu zostało zablokowane. Uruchom logowanie ponownie.

„Konto z tym adresem e-mail już istnieje”: dostawca nie potwierdził e-maila (zawsze w przypadku Facebooka, chyba że włączona jest opcja „Ufaj także adresom e-mail z Facebooka przy automatycznym powiązaniu”) albo automatyczne łączenie jest wyłączone. Klient loguje się hasłem, a następnie łączy usługę na stronie Połączone konta.

„Zbyt wiele prób. Odczekaj kilka minut.”: osiągnięto limit dla adresu IP. Odczekaj 15 minut albo podnieś próg w zakładce Zachowanie, na przykład w firmie, w której wszystkie stanowiska korzystają z jednego adresu IP.

Przycisk się nie wyświetla: sprawdź w pasku konfiguracji, czy usługa ma stan „aktywny”, a nie „niekompletny”. Następnie wyczyść pamięć podręczną PrestaShop.

Kupon powitalny nie jest tworzony: sprawdź, czy opcja jest włączona i czy kwota jest większa od zera. Kupon powstaje tylko dla nowego konta, a nie przy przypisaniu usługi do istniejącego konta.