# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfsocialconnect-sw/index.md), [en](https://www.datafirefly.com/en/documentation/dfsocialconnect-sw-2/index.md), [es](https://www.datafirefly.com/es/documentation/dfsocialconnect-sw-3/index.md), [de](https://www.datafirefly.com/de/documentation/dfsocialconnect-sw-4/index.md), [it](https://www.datafirefly.com/it/documentation/dfsocialconnect-sw-5/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsocialconnect-sw/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsocialconnect-sw/index.md)
- Indeks:
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.
Apple Sign In wymaga poważnej konfiguracji po stronie Apple Developer (Services ID, Team ID, Key ID, klucz .p8) i prawidłowej domeny HTTPS. Bez tych elementów działać będą wyłącznie Google i Facebook. Moduł doskonale działa także z jednym włączonym dostawcą.
## 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.
Na Shopware 6.7 nowa administracja Meteor ładuje moduły pluginów automatycznie, bez builda administracji. Na 6.6, jeśli menu "Social Connect" pod Klientami nie wyświetla się po instalacji, uruchom `bin/console administration:build`, a następnie wyczyść cache przeglądarki.
## 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: Włącz przełącznik **Włącz Sign in with Apple**.
- **Services ID** (np. `com.twoja-marka.web`),
- **Team ID**,
- **Key ID**,
- **Klucz prywatny**: wklej pełną zawartość pliku `.p8`, łącznie z liniami BEGIN/END.
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.
**Pułapka callbacku Apple form_post.** Gdy żądany jest scope `name email`, Apple odsyła callback metodą POST cross-site, co uniemożliwia odesłanie cookie sesji SameSite Lax. Większość integracji psuje się w tym miejscu. DfSocialConnect ustawia równolegle cookie state podpisane HMAC w SameSite None i rewaliduje przez to cookie, gdy sesja jest niedostępna. Z Twojej strony nie jest wymagana żadna konfiguracja, ale zakłada to, że Twój sklep jest serwowany po ścisłym HTTPS (cookies SameSite=None wymagają `Secure`).
## 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ć.