DataFirefly Social Connect: dokumentacja

Prezentacja

DataFirefly Social Connect dodaje do PrestaShop 8 i 9 trzy przyciski logowania społecznościowego (Google, Apple, Facebook) połączone z kompletnym pulpitem analitycznym. Moduł nie ogranicza się do uwierzytelniania: mierzy konwersję, automatycznie generuje kupony powitalne, zasila Twój CRM przez podpisany webhook i pozostaje w 100% zgodny z RODO.

Cel jest podwójny: usunąć tarcie rejestracji (jedno kliknięcie zamiast formularza) i zmierzyć rzeczywisty wpływ na Twój biznes (kliknięcia, konwersje, przychód generowany przez klientów społecznościowych).

Instalacja

1. Pobierz archiwum dfsocialconnect.zip ze swojego konta klienta na datafirefly.com.
2. W zapleczu PrestaShop przejdź do Moduły > Menedżer modułów > Zainstaluj 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) oraz ukrytą zakładkę zaplecza AdminDfSocialConnect.
4. Kliknij Konfiguruj. Trafiasz na pusty pulpit: pierwsze dane pojawią się, gdy tylko użytkownik kliknie przycisk społecznościowy.

Moduł jest zgodny z PrestaShop od 8.0.0 do 9.99.99 i z PHP od 7.4 do 8.3. Nie wymaga żadnej zewnętrznej zależności Composera: minimalny autoloader PSR-4 jest w zestawie.

Konfiguracja providerów

Każdy provider wymaga danych logowania OAuth uzyskanych z jego konsoli deweloperskiej. Moduł wyświetla dokładny adres callback do skopiowania do każdej konsoli. To najważniejszy etap: najmniejsza literówka powoduje błąd redirect_uri_mismatch.

Google OAuth2 i OpenID Connect

1. Wejdź na https://console.cloud.google.com/apis/credentials.
2. Utwórz lub wybierz projekt, a następnie kliknij Utwórz dane logowania > Identyfikator klienta OAuth 2.0.
3. Typ aplikacji: Aplikacja internetowa.
4. W polu Autoryzowane identyfikatory URI przekierowania wklej adres wyświetlony w zakładce „Providers” konfiguracji modułu (postać: https://twoj-sklep.pl/module/dfsocialconnect/callback?provider=google).
5. Odczytaj Client ID i Client Secret i wklej je do modułu.
6. Włącz przełącznik „Google włączony”.

Apple Sign In

1. Wejdź na https://developer.apple.com/account/resources/identifiers/list (wymagane płatne konto deweloperskie Apple).
2. Utwórz Services ID (nie App ID). Zanotuj jego identyfikator: to Twój Client ID.
3. Włącz Sign In with Apple dla tego Services ID, skonfiguruj domenę swojego sklepu i wklej adres callback wyświetlony przez moduł (provider=apple) jako Return URL.
4. W sekcji Keys utwórz nowy klucz z włączonym Sign In with Apple. Pobierz plik .p8: nigdy więcej nie będziesz mógł go odzyskać.
5. Odczytaj swój Team ID (prawy górny róg konsoli Apple), swój Key ID (identyfikator klucza utworzonego w kroku 4) oraz całą zawartość pliku .p8 (razem z liniami BEGIN PRIVATE KEY i END PRIVATE KEY).
6. Wklej te 4 pola do konfiguracji modułu (Services ID, Team ID, Key ID, zawartość .p8).
7. Włącz przełącznik „Apple włączony”.

Moduł podpisuje JWT client_secret algorytmem ES256 w locie i regeneruje go automatycznie co 5 miesięcy (maksymalna ważność dopuszczona przez Apple to 6 miesięcy). Nie musisz zarządzać żadną ręczną rotacją.

Facebook Login

1. Wejdź na https://developers.facebook.com/apps.
2. Utwórz nową aplikację typu Konsumenci.
3. W sekcji Add products dodaj Facebook Login.
4. W Facebook Login > Settings wklej adres callback wyświetlony przez moduł (provider=facebook) w polu Valid OAuth Redirect URIs.
5. Odczytaj App ID i App Secret w Settings > Basic i wklej je do modułu.
6. Włącz przełącznik „Facebook włączony”.

Moduł korzysta z Graph API v19.0 i automatycznie włącza appsecret_proof, co uniemożliwia odtworzenie skradzionego access tokenu, wymagając podpisu HMAC sekretem aplikacji.

Zakładka Zachowanie

Ta zakładka steruje tym, co dzieje się po udanym logowaniu społecznościowym.

• Auto-link po zweryfikowanym e-mailu: jeśli e-mail zwrócony przez providera jest oznaczony jako zweryfikowany i odpowiada istniejącemu kontu klienta, moduł automatycznie wiąże providera z tym kontem zamiast tworzyć nowe. Zalecane: włączone.
• Import awatara: pobiera zdjęcie profilowe do /img/dfsc/avatars/<id_customer>.<ext> (limit 2 MB, biała lista MIME JPEG, PNG, WebP). Przeżywa wygaśnięcie CDN providera.
• Kupon powitalny: dla każdego nowego konta utworzonego przez logowanie społecznościowe moduł tworzy jednorazową regułę koszyka PrestaShop na nazwisko klienta. Skonfiguruj prefiks (domyślnie WELCOME), kwotę i okres ważności.
• Grupa klientów per provider: przypisz ID grupy PrestaShop do każdego providera (Google, Apple, Facebook). Przydatne do segmentacji kampanii marketingowych według pochodzenia.
• Domyślny opt-in newslettera: po włączeniu utworzony klient jest oznaczany jako zapisany do newslettera (włączaj tylko wtedy, gdy Twój proces obejmuje zgodny z RODO double opt-in).
• Rate limiting: maksymalna liczba prób z jednego IP w oknie 15 minut. Domyślnie 30 prób. Powyżej użytkownik otrzymuje komunikat „Zbyt wiele prób”.
• Retencja logów: liczba dni przechowywania surowych logów (ps_dfsc_log i ps_dfsc_button_click). Dzienny rollup (ps_dfsc_stats_daily) jest przechowywany bezterminowo i zasila pulpit.

Zakładka Wygląd

Wybierz wizualną formę przycisków:

• Styl: 5 wariantów, rounded (domyślny, narożniki 8 px), pill (całkowicie zaokrąglony), square (kanciasty), ghost (przezroczysty z obramowaniem), minimal (kompaktowy).
• Tryb etykiety: 3 tryby, Kontynuuj z X (domyślny, neutralny), Zaloguj się przez X (strona logowania), Zarejestruj się przez X (strona rejestracji).
• Pokaż na stronie logowania i Pokaż na stronie rejestracji: niezależne przełączniki.
• Widget Moje konto: wyświetla w panelu klienta sekcję „Połączone konta”, pozwalającą powiązać lub odwiązać każdego providera w dowolnym momencie (wymóg RODO).

Pulpit analityczny

Pierwsza zakładka konfiguracji agreguje statystyki domyślnie z ostatnich 30 dni (wartość konfigurowalna).

• 4 karty KPI: Udane logowania, Kliknięcia w przyciski, Nowi utworzeni klienci, Niepowodzenia.
• Krzywa czasowa: udane logowania dziennie, z podziałem na providerów (Google niebieski, Apple czarny, Facebook w niebieskim Meta).
• Podział per provider: wykres pierścieniowy Chart.js z udziałem procentowym każdego providera.
• Współczynnik konwersji per provider: kliknięcie kontra udane logowanie. Pozwala wykryć źle skonfigurowanego providera (nienaturalnie niski współczynnik).
• Podział urządzeń i przeglądarek: wykres słupkowy zagregowany w oknie czasowym.
• Heatmapa dzień × godzina: siatka 7 × 24 w 7 odcieniach niebieskiego. Zidentyfikuj szczyty użycia, aby dopasować kampanie.
• Penetracja społecznościowa: odsetek Twojej bazy klientów, który ma powiązanego co najmniej jednego providera.
• Przychód generowany przez klientów społecznościowych: suma opłaconych zamówień klientów utworzonych przez logowanie społecznościowe, wyliczana złączeniem SQL na ps_orders.

Webhook CRM

Przy każdym udanym logowaniu lub powiązaniu konta moduł może wysłać żądanie HTTP POST na wybrany przez Ciebie adres, w trybie fire-and-forget (czas odpowiedzi Twojego endpointu nie wpływa na czas logowania użytkownika).

• Adres webhooka: zalecany endpoint HTTPS. Make, n8n, Zapier albo Twój wewnętrzny stack.
• Wspólny sekret: używany do podpisania payloadu algorytmem HMAC-SHA256. Podpis jest wysyłany w nagłówku X-Dfsc-Signature. Po stronie odbiorczej przelicz HMAC na surowej treści, aby zweryfikować autentyczność.

Przykładowy wysyłany payload:

{
  "event": "social_login_success",
  "provider": "google",
  "id_customer": 1234,
  "email": "maria.kowalska@example.com",
  "is_new_account": true,
  "ip": "203.0.113.42",
  "timestamp": 1748378400
}

RODO i zgoda

Moduł został zaprojektowany tak, aby respektować RODO by design:

• Przy każdym logowaniu społecznościowym do ps_dfsc_consent trafia wiersz ze znacznikiem czasu, IP, user agentem i providerem. To Twój audit trail.
• Widget „Połączone konta” w Moim koncie pozwala klientowi odwiązać providera w dowolnym momencie.
• Odinstalowanie modułu czysto usuwa 5 tabel i wszystkie klucze konfiguracji. Konta klientów pozostają nietknięte.
• Żaden sekret OAuth nie jest nigdy przesyłany jawnie: cała wymiana odbywa się przez HTTPS, a JWT Apple jest podpisywany lokalnie Twoim kluczem .p8.

Odinstalowanie

Odinstaluj moduł w Moduły > Menedżer modułów. Proces:

1. Usuwa 5 tabel ps_dfsc_*.
2. Usuwa zakładkę zaplecza AdminDfSocialConnect.
3. Usuwa wszystkie klucze konfiguracji DFSC_*.
4. Powiązania społecznościowe klientów są kasowane, ale konta klientów i ich zamówienia pozostają nietknięte. Awatary zapisane w /img/dfsc/avatars/ są usuwane.

Rozwiązywanie problemów

Błąd „redirect_uri_mismatch” (Google): adres wklejony do konsoli Google nie odpowiada dokładnie temu, który wyświetla moduł. Sprawdź schemat (https), domenę (z www lub bez) i pełną ścieżkę. Żadnych znaków na końcu (ukośnik, spacja).

Błąd „invalid_client” (Apple): Twój JWT client_secret jest nieprawidłowy. Częste przyczyny: błędny Team ID lub Key ID, ucięta zawartość .p8 (sprawdź linie BEGIN i END PRIVATE KEY) albo pomylenie Services ID z App ID.

Błąd „Invalid OAuth access token signature” (Facebook): Twój App Secret jest błędny. Wygeneruj go ponownie w Settings > Basic i wklej jeszcze raz.

„Zbyt wiele prób, zaczekaj chwilę”: zadziałał rate limiter. Albo odczekaj 15 minut, albo podnieś próg w zakładce Zachowanie.

Statystyki nie rosną: sprawdź, czy do ps_dfsc_button_click faktycznie trafiają wiersze (jedno kliknięcie w trybie incognito powinno wystarczyć). Jeśli nic się nie zapisuje, kontroler frontowy jest prawdopodobnie nieosiągalny: sprawdź swoje reguły przepisywania adresów.

Kupon powitalny nie jest tworzony: sprawdź, czy funkcja jest włączona w zakładce Zachowanie, czy kwota i prefiks są wypełnione i czy konto klienta faktycznie zostało utworzone (a nie tylko powiązane z istniejącym kontem: auto-link nie generuje kuponu).