DataFirefly Social Connect — Dokumentation

Übersicht

DataFirefly Social Connect fügt PrestaShop 8 und 9 drei Social-Login-Buttons (Google, Apple, Facebook) hinzu, gekoppelt mit einem vollständigen Analyse-Dashboard. Das Modul authentifiziert nicht nur: Es misst die Conversion, vergibt automatisch Willkommensgutscheine, speist Ihr CRM über einen signierten Webhook und bleibt zu 100% DSGVO-konform.

Das Ziel ist zweifach: Reibungsverlust bei der Registrierung beseitigen (ein Klick statt eines Formulars) und den echten Geschäftseffekt messen (Klicks, Conversions, durch Social-Kunden erzeugter Umsatz).

Installation

1. Laden Sie das Archiv dfsocialconnect.zip aus Ihrem Kundenkonto auf datafirefly.com herunter.
2. Gehen Sie im PrestaShop-Backoffice zu Module > Modulverwaltung > Modul hochladen und legen Sie die ZIP ab.
3. Klicken Sie auf Installieren. Das Modul erstellt 5 Tabellen (ps_dfsc_identity, ps_dfsc_log, ps_dfsc_stats_daily, ps_dfsc_button_click, ps_dfsc_consent) und einen versteckten BO-Tab AdminDfSocialConnect.
4. Klicken Sie auf Konfigurieren. Sie landen auf einem leeren Dashboard — die ersten Datenpunkte erscheinen, sobald ein Nutzer auf einen Social-Button klickt.

Das Modul ist mit PrestaShop 8.0.0 bis 9.99.99 und PHP 7.4 bis 8.3 kompatibel. Keine externe Composer-Abhängigkeit erforderlich: Ein minimaler PSR-4-Autoloader ist inbegriffen.

Provider-Konfiguration

Jeder Provider erfordert OAuth-Zugangsdaten, die aus seiner Developer-Konsole stammen. Das Modul zeigt die exakte Callback-URL an, die in jede Konsole eingefügt werden muss — das ist der wichtigste Schritt: Jeder Tippfehler verursacht einen redirect_uri_mismatch-Fehler.

Google OAuth2 / OpenID Connect

1. Gehen Sie zu https://console.cloud.google.com/apis/credentials.
2. Erstellen Sie ein Projekt oder wählen Sie eines aus, dann klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
3. Anwendungstyp: Webanwendung.
4. Unter Autorisierte Weiterleitungs-URIs fügen Sie die im Tab „Provider“ der Modulkonfiguration angezeigte URL ein (Format: https://ihr-shop.com/module/dfsocialconnect/callback?provider=google).
5. Kopieren Sie die Client-ID und das Client-Secret und fügen Sie sie ins Modul ein.
6. Aktivieren Sie den Toggle „Google aktiviert“.

Apple Sign In

1. Gehen Sie zu https://developer.apple.com/account/resources/identifiers/list (kostenpflichtiger Apple-Developer-Account erforderlich).
2. Erstellen Sie eine Services ID (keine App ID). Notieren Sie ihren Identifier — das ist Ihre Client ID.
3. Aktivieren Sie Sign In with Apple auf dieser Services ID, konfigurieren Sie Ihre Shop-Domain und fügen Sie die vom Modul angezeigte Callback-URL (provider=apple) als Return URL ein.
4. Unter Keys erstellen Sie einen neuen Schlüssel mit aktiviertem Sign In with Apple. Laden Sie die .p8-Datei herunter — Sie können sie nie wieder abrufen.
5. Holen Sie sich Ihre Team ID (oben rechts in der Apple-Konsole), Ihre Key ID (der Identifier des in Schritt 4 erstellten Schlüssels) und den vollständigen Inhalt der .p8-Datei (einschließlich der Zeilen BEGIN PRIVATE KEY und END PRIVATE KEY).
6. Fügen Sie alle 4 Felder in die Modulkonfiguration ein (Services ID, Team ID, Key ID, .p8-Inhalt).
7. Aktivieren Sie den Toggle „Apple aktiviert“.

Das Modul signiert das ES256 client_secret JWT zur Laufzeit und erneuert es automatisch alle 5 Monate (die maximal von Apple erlaubte Gültigkeit beträgt 6 Monate). Keine manuelle Rotation erforderlich.

Facebook Login

1. Gehen Sie zu https://developers.facebook.com/apps.
2. Erstellen Sie eine neue App vom Typ Verbraucher.
3. Im Abschnitt Add products fügen Sie Facebook Login hinzu.
4. Unter Facebook Login > Settings fügen Sie die vom Modul angezeigte Callback-URL (provider=facebook) in Valid OAuth Redirect URIs ein.
5. Holen Sie sich die App ID und das App Secret unter Settings > Basic und fügen Sie sie ins Modul ein.
6. Aktivieren Sie den Toggle „Facebook aktiviert“.

Das Modul verwendet die Graph API v19.0 und aktiviert automatisch appsecret_proof, was das erneute Verwenden eines gestohlenen Access Tokens verhindert, indem es eine HMAC-Signatur des App-Secrets erfordert.

Tab Verhalten

Dieser Tab steuert, was nach erfolgreichem Social Login passiert.

• Auto-Verknüpfung per verifizierter E-Mail — wenn die vom Provider zurückgegebene E-Mail als verifiziert markiert ist und mit einem bestehenden Kundenkonto übereinstimmt, verknüpft das Modul den Provider automatisch mit diesem Konto, statt ein neues zu erstellen. Empfohlen: ON.
• Avatar importieren — lädt das Profilbild nach /img/dfsc/avatars/<id_customer>.<ext> herunter (Limit 2 MB, MIME-Whitelist JPEG/PNG/WebP). Überlebt CDN-Ablauf beim Provider.
• Willkommensgutschein — für jedes neue Konto, das via Social Login erstellt wird, erzeugt das Modul eine einmal verwendbare PrestaShop CartRule auf den Kundennamen. Konfigurieren Sie den Präfix (Standard WELCOME), den Betrag und die Gültigkeitsdauer.
• Kundengruppe pro Provider — weisen Sie jedem Provider eine PrestaShop-Gruppen-ID zu (Google / Apple / Facebook). Nützlich, um Ihre Marketing-Kampagnen nach Herkunft zu segmentieren.
• Standard Newsletter-Opt-in — wenn aktiviert, wird der erstellte Kunde als abonniert markiert (nur aktivieren, wenn Ihr Prozess ein DSGVO-konformes Double-Opt-in enthält).
• Rate Limiting — maximale Anzahl an Versuchen pro IP in einem 15-Minuten-Fenster. Standard: 30. Danach erhält der Nutzer die Meldung „Zu viele Versuche“.
• Log-Aufbewahrung — Anzahl der Tage, die Rohlogs (ps_dfsc_log und ps_dfsc_button_click) aufbewahrt werden. Das tägliche Rollup (ps_dfsc_stats_daily) wird unbegrenzt aufbewahrt und versorgt das Dashboard.

Tab Erscheinungsbild

Wählen Sie die visuelle Darstellung der Buttons:

• Stil — 5 Varianten: rounded (Standard, 8 px Ecken), pill (vollständig abgerundet), square (kantig), ghost (transparent mit Rahmen), minimal (kompakt).
• Beschriftungsmodus — 3 Modi: Weiter mit X (Standard, neutral), Anmelden mit X (Login-Seite), Registrieren mit X (Registrierungs-Seite).
• Auf Login-Seite anzeigen und Auf Registrierungs-Seite anzeigen — unabhängige Toggles.
• Mein-Konto-Widget — zeigt im Kundenbereich einen Abschnitt „Verbundene Konten“, über den der Kunde jeden Provider jederzeit verbinden oder trennen kann (DSGVO-Anforderung).

Analyse-Dashboard

Der erste Tab der Konfiguration aggregiert die Statistiken standardmäßig über ein gleitendes 30-Tage-Fenster (konfigurierbar).

• 4 KPI-Karten — Erfolgreiche Anmeldungen, Button-Klicks, Neue erstellte Kunden, Fehler.
• Zeitreihen-Kurve — erfolgreiche Anmeldungen pro Tag, nach Provider segmentiert (Google blau, Apple schwarz, Facebook Meta-blau).
• Provider-Aufteilung — Chart.js-Doughnut mit dem Prozentsatz jedes Providers.
• Conversion-Rate pro Provider — Klick vs. erfolgreiche Anmeldung. Identifiziert einen falsch konfigurierten Provider (anomal niedrige Rate).
• Geräte- und Browser-Aufteilung — über das Fenster aggregiertes Balkendiagramm.
• Tag-x-Stunde-Heatmap — 7-x-24-Raster in 7 Blautönen. Identifizieren Sie Nutzungspeaks, um Ihre Kampagnen anzupassen.
• Social-Durchdringung — Prozentsatz Ihrer Kundenbasis, der mindestens einen Provider verknüpft hat.
• Umsatz durch Social-Kunden — Summe der bezahlten Bestellungen von Kunden, die per Social Login erstellt wurden, berechnet per SQL-JOIN auf ps_orders.

CRM-Webhook

Bei jeder erfolgreichen Anmeldung oder Konto-Verknüpfung kann das Modul eine HTTP-POST-Anfrage an eine URL Ihrer Wahl senden, im fire-and-forget-Modus (die Reaktionszeit Ihres Endpunkts beeinflusst die Login-Zeit des Nutzers nicht).

• Webhook-URL — HTTPS-Endpunkt empfohlen. Make, n8n, Zapier oder Ihr eigener Stack.
• Geteiltes Geheimnis — wird verwendet, um die Payload via HMAC-SHA256 zu signieren. Die Signatur wird im Header X-Dfsc-Signature gesendet. Auf der Empfängerseite berechnen Sie das HMAC über den rohen Body neu, um die Authentizität zu validieren.

Beispiel-Payload:

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

DSGVO und Einwilligung

Das Modul ist DSGVO-konform by design ausgelegt:

• Bei jedem Social Login wird eine Zeile in ps_dfsc_consent mit Zeitstempel, IP, User Agent und Provider eingefügt — das ist Ihr Audit Trail.
• Das Widget „Verbundene Konten“ in Mein Konto erlaubt dem Kunden, einen Provider jederzeit zu trennen.
• Die Deinstallation des Moduls entfernt sauber die 5 Tabellen und alle Konfigurationsschlüssel. Die Kundenkonten bleiben unberührt.
• Kein OAuth-Geheimnis wird jemals im Klartext übertragen: Alle Austausche laufen über HTTPS und das Apple JWT wird lokal mit Ihrem .p8-Schlüssel signiert.

Deinstallation

Aus Module > Modulverwaltung deinstallieren Sie das Modul. Der Prozess:

1. Entfernt die 5 Tabellen ps_dfsc_*.
2. Entfernt den BO-Tab AdminDfSocialConnect.
3. Entfernt alle Konfigurationsschlüssel DFSC_*.
4. Die sozialen Verknüpfungen der Kunden werden gelöscht, aber die Kundenkonten und ihre Bestellungen bleiben unberührt. Die im Cache liegenden Avatare in /img/dfsc/avatars/ werden entfernt.

Fehlerbehebung

„redirect_uri_mismatch“-Fehler (Google) — die in die Google-Konsole eingefügte URL stimmt nicht exakt mit der vom Modul angezeigten überein. Prüfen Sie das Schema (https), die Domain (mit oder ohne www) und den vollständigen Pfad. Keine nachfolgenden Zeichen (Slash, Leerzeichen).

„invalid_client“-Fehler (Apple) — Ihr client_secret JWT ist ungültig. Häufige Ursachen: falsche Team ID oder Key ID, abgeschnittener .p8-Inhalt (prüfen Sie die Zeilen BEGIN/END PRIVATE KEY), oder Services ID mit App ID verwechselt.

„Invalid OAuth access token signature“-Fehler (Facebook) — Ihr App Secret ist falsch. Generieren Sie es unter Settings > Basic neu und fügen Sie es erneut ein.

„Zu viele Versuche, bitte warten“ — der Rate Limiter wurde ausgelöst. Warten Sie entweder 15 Minuten oder erhöhen Sie die Schwelle unter Verhalten.

Die Statistiken steigen nicht — prüfen Sie, dass ps_dfsc_button_click tatsächlich Zeilen erhält (ein Klick im Inkognito-Modus sollte reichen). Wird nichts geschrieben, ist der Frontend-Controller wahrscheinlich nicht erreichbar: prüfen Sie Ihre URL-Rewriting-Regeln.

Der Willkommensgutschein wird nicht erstellt — prüfen Sie, dass die Funktion unter Verhalten aktiviert ist, dass der Betrag und der Präfix ausgefüllt sind, und dass das Kundenkonto tatsächlich erstellt wurde (nicht nur mit einem bestehenden verknüpft — die Auto-Verknüpfung gibt keinen Gutschein aus).