DfSocialConnect SW: kompletny przewodnik

DfSocialConnect dodaje do Shopware 6 logowanie społecznościowe Google, Apple i Facebook wraz z kompletnym pulpitem analitycznym wbudowanym w administrację. Plugin jest celowo zbudowany bez zewnętrznej biblioteki JWT: podpis ES256 dla client_secret Apple jest generowany natywnie w PHP przez openssl. Jeden codebase obejmuje Shopware 6.6 i 6.7, bez wymuszonego builda storefrontu ani własnej administracji. Ten przewodnik obejmuje instalację, konfigurację każdego dostawcy per kanał sprzedaży, wyświetlanie przycisków, pulpit, automatyczne łączenie kont, bezpieczeństwo i rozwiązywanie problemów.

Wymagania

• Shopware 6.6.x lub 6.7.x (6.5 nie jest obsługiwane, plugin używa AccountService::loginById wprowadzonego w 6.6).
• PHP 8.2 lub nowszy, z rozszerzeniem openssl (używanym do podpisu ES256 i HMAC cookie state).
• Prawidłowy adres HTTPS Twojego sklepu: wszyscy dostawcy OAuth odrzucają URI przekierowania po HTTP w produkcji.

Instalacja

1. Pobierz DfSocialConnect-v1.0.1.zip ze swojego konta DataFirefly.
2. Zainstaluj ZIP przez Administracja → Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie albo skopiuj rozpakowany katalog DfSocialConnect do custom/plugins/.
3. Aktywuj plugin i odśwież cache:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfSocialConnect
   bin/console cache:clear

4. Przy instalacji plugin tworzy dwie tabele: df_social_account (tożsamości społecznościowe powiązane z klientami) i df_social_log (dziennik zdarzeń dla pulpitu). Przy odinstalowaniu bez zachowania danych obie tabele są usuwane.

Konfiguracja ogólna

Otwórz Rozszerzenia → Moje rozszerzenia → DataFirefly Social Connect → ⋯ → Konfiguruj. Wszystkie opcje można zawęzić do kanału sprzedaży natywnym selektorem u góry strony: wybierz kanał, aby przypisać mu konkretne wartości, albo zostaw “Wszystkie kanały sprzedaży” dla wartości wspólnych.

Karta Ogólne zawiera:

• Styl przycisków: “pełny kolor” (domyślnie, w oficjalnych barwach), “kontur” (stonowany wariant dla motywów minimalistycznych) albo “sama ikona” (bardzo kompaktowy, idealny na mobile).
• Łącz automatycznie po zweryfikowanym e-mailu: jeśli dostawca poświadcza e-mail, a istnieje klient o tym adresie, tożsamość społecznościowa jest przypinana do tego konta zamiast tworzenia duplikatu. Domyślnie włączone.
• Pomiń double opt-in: e-maile dostarczane przez Google, Apple i Facebook są już zweryfikowane, więc double opt-in jest domyślnie pomijany.
• Newsletter przy rejestracji: dodaje flagę zgody na newsletter na kontach utworzonych przez logowanie społecznościowe.
• Próby na godzinę (per IP): próg rate limitingu przepływu uwierzytelniania. Domyślnie 30, zwiększ, jeśli masz wielu odwiedzających za tym samym NAT-em.

Google Connect

1. Wejdź na console.cloud.google.com → Interfejsy API i usługi → Dane logowania.
2. Utwórz identyfikator klienta OAuth 2.0, typ Aplikacja internetowa.
3. W Autoryzowanych identyfikatorach URI przekierowania dodaj:

   https://twoja-domena/df-social-connect/callback/google

   Przy wielu kanałach dodaj po jednej linii na domenę kanału sprzedaży.

4. Skopiuj Client ID i Client Secret do karty Google Connect w konfiguracji pluginu i włącz przełącznik Włącz Google Connect.

Przepływ to OpenID Connect z PKCE S256, żądany scope to openid email profile, a nonce id_token jest walidowany po stronie serwera przy każdym powrocie.

Apple Connect

Apple jest bardziej wymagające w konfiguracji, ale oferuje najlepsze doświadczenie użytkownika na iOS i macOS.

1. Wejdź na developer.apple.com → Certificates, Identifiers and Profiles.
2. Utwórz App ID z uprawnieniem Sign In with Apple.
3. Utwórz Services ID (na przykład com.twoja-marka.web) powiązany z App ID. W jego konfiguracji:
   • Domains: Twoja domena (bez https://).
   • Return URLs: https://twoja-domena/df-social-connect/callback/apple.
4. Utwórz Key z usługą Sign In with Apple, pobierz plik AuthKey_XXXXX.p8 i zanotuj jego Key ID.
5. Odczytaj swój Team ID w prawym górnym rogu portalu.
6. W karcie Apple Connect pluginu uzupełnij:
   • Services ID (np. com.twoja-marka.web),
   • Team ID,
   • Key ID,
   • Klucz prywatny: wklej pełną zawartość pliku .p8, łącznie z liniami BEGIN/END.

   Włącz przełącznik Włącz Sign in with Apple.

Client_secret JWT podpisany w ES256 jest generowany w locie przy każdym żądaniu na podstawie klucza .p8, bez cache: nie ma żadnej rotacji do obsługi.

Facebook Connect

1. Wejdź na developers.facebook.com → Moje aplikacje i utwórz App typu Consumer.
2. Dodaj produkt Facebook Login → Settings.
3. W Valid OAuth Redirect URIs dodaj:

   https://twoja-domena/df-social-connect/callback/facebook

4. Odczytaj App ID i App Secret w Settings → Basic i wklej je do karty Facebook Connect pluginu. Włącz przełącznik.

Moduł wywołuje Graph API v21.0 z obowiązkowym appsecret_proof (podpis HMAC-SHA256 tokenu Twoim App Secret), co Facebook zaleca dla każdej aplikacji produkcyjnej.

Wyświetlanie przycisków w storefroncie

Gdy przynajmniej jeden dostawca jest włączony i skonfigurowany, przyciski pojawiają się automatycznie:

• na stronie /account/login, tuż pod formularzem logowania, poprzedzone separatorem “albo kontynuuj przez”;
• na stronie /account/register, w tym samym miejscu;
• na stronie profilu klienta (/account/profile) blok Połączenia społecznościowe wymienia już powiązane tożsamości z przyciskiem Odłącz przy każdej z nich i dodatkowo proponuje wciąż dostępnych dostawców.

Nie jest potrzebne żadne nadpisanie motywu. Szablony Twig pluginu rozszerzają bloki page_account_login_login, page_account_register_content i page_account_profile_personal Shopware. Jeśli Twój niestandardowy motyw już nadpisuje te bloki i pomija wywołanie {{ parent() }}, dodaj je, aby przywrócić przyciski.

Personalizacja stylu

Przyciski są stylowane przez Resources/app/storefront/src/scss/base.scss. Dostępne są trzy warianty bazowe (--default, --outline, --icon); aby pójść dalej, nadpisz klasy .df-social-connect__btn--google, --apple i --facebook w swoim motywie.

Pulpit analityczny

Administracja udostępnia dedykowany moduł w Klienci → Social Connect. Cztery karty filtrowalne po okresie (7, 30 albo 90 dni) i po kanale sprzedaży:

• Przegląd: logowania, rejestracje, powiązane konta, ogólny współczynnik powodzenia, błędy.
• Per dostawca: paski postępu w oficjalnych barwach każdej marki.
• Trend dzienny: wykres wieloseryjny ApexCharts (jedna linia na dostawcę).
• Ostatnia aktywność: 25 najnowszych zdarzeń z klientem, dostawcą, typem zdarzenia i komunikatem.

Moduł jest chroniony dedykowanym ACL viewer: df_social_connect.viewer. Aby dać roli użytkownika dostęp do pulpitu, otwórz jej profil w Ustawienia → System → Użytkownicy i uprawnienia i zaznacz odpowiednie uprawnienie w kategorii Klienci.

Automatyczne łączenie i ochrona przed duplikatami

Przy każdym logowaniu społecznościowym plugin próbuje trzech kolejnych rozstrzygnięć:

1. Bezpośrednie wyszukanie po parze (dostawca, provider_user_id) w df_social_account. Znaleziono: natychmiastowe logowanie na powiązanego klienta.
2. Łączenie po zweryfikowanym e-mailu: jeśli dostawca oznaczył e-mail jako zweryfikowany, a klient o tym adresie istnieje w danym kanale sprzedaży, tożsamość społecznościowa jest przypinana do tego konta. Zachowuje historię zamówień i grupę klienta.
3. Utworzenie konta: wyłącznie w ostateczności tworzony jest nowy klient przez AccountService::loginById, z losowym, nigdy nieużywanym ponownie hasłem, neutralną formą grzecznościową i minimalnym adresem powiązanym z domyślnym krajem kanału sprzedaży.

Automatyczne łączenie po e-mailu wyłącza się per kanał sprzedaży w konfiguracji ogólnej, jeśli wolisz wymusić jawne tworzenie konta przy każdej rejestracji społecznościowej.

Bezpieczeństwo

• State OAuth podpisany HMAC: ochrona CSRF we wszystkich przepływach.
• PKCE S256 w Google: code_verifier nigdy nie opuszcza serwera.
• Nonce OIDC walidowany po stronie serwera w id_token Google.
• appsecret_proof Facebooka: token użytkownika nie może zostać odtworzony z innego klienta.
• Hashowane IP: adresy IP zdarzeń są hashowane przed zapisem w df_social_log.
• Rate limiting per IP, próg konfigurowalny na godzinę.
• Sanityzacja przeciw open redirect: adresy powrotne podane przez użytkownika są weryfikowane względem domeny kanału sprzedaży przed jakimkolwiek przekierowaniem.

Odinstalowanie

W Moich rozszerzeniach dezaktywuj, a następnie odinstaluj plugin. Jeśli opcja Zachowaj dane użytkownika jest wyłączona, obie tabele df_social_account i df_social_log zostaną usunięte. Konta klientów pozostają nienaruszone: kasowane są wyłącznie powiązania społecznościowe i dziennik zdarzeń.

FAQ i rozwiązywanie problemów

Na stronie logowania nie wyświetla się żaden przycisk. Sprawdź, czy (a) przynajmniej jeden dostawca ma włączony przełącznik ORAZ uzupełnione dane dostępowe w konfiguracji; (b) czy jesteś na skonfigurowanym kanale sprzedaży; (c) czy motyw został przekompilowany: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple zwraca invalid_client. Client_secret JWT został odrzucony po stronie Apple. Sprawdź Services ID, Team ID, Key ID i to, czy zawartość klucza .p8 zawiera linie BEGIN i END. Rozjechany czas serwera również wywołuje ten błąd, ponieważ JWT ma iat w przyszłości.

Apple zwraca błąd state przy powrocie. Sprawdź, czy Twój sklep jest serwowany po ścisłym HTTPS (bez przekierowania HTTP → HTTPS na callbacku) i czy Twoje cookies firm trzecich nie są blokowane przez proxy frontowe przepisujące SameSite=None.

Facebook zwraca Invalid appsecret_proof provided. Wpisany App Secret nie odpowiada App ID. Wygeneruj go ponownie w Settings → Basic swojej aplikacji Facebooka i wklej na nowo.

Pulpit jest pusty, mimo że były logowania. Sprawdź filtr kanału sprzedaży u góry pulpitu: ogranicza on wszystkie statystyki. Wybierz “Wszystkie kanały sprzedaży”, aby zobaczyć agregat globalny.

Użytkownik ma dwa konta: jedno z formularza, drugie z Google. Automatyczne łączenie po e-mailu było wyłączone albo e-mail pierwotnego konta nie był dokładnie taki sam jak zwrócony przez Google. Aby je scalić, usuń nowsze konto, a następnie poproś użytkownika o ponowne zalogowanie przez Google: automatyczne łączenie przypnie go do zachowanego konta.

Czy zgodne z Shopware 6.5? Nie. AccountService::loginById zostało wprowadzone w 6.6; ten mechanizm jest centralny dla pluginu i nie da się go czysto zbackportować.