DataFirefly Social Connect — Documentazione

Presentazione

DataFirefly Social Connect aggiunge a PrestaShop 8 e 9 tre pulsanti di accesso social (Google, Apple, Facebook) accompagnati da una dashboard analitica completa. Il modulo non si limita ad autenticare: misura la conversione, genera automaticamente buoni di benvenuto, alimenta il tuo CRM tramite un webhook firmato e resta al 100% conforme al GDPR.

L’obiettivo è duplice: eliminare l’attrito di registrazione (un click invece di un form) e misurare l’impatto reale sul business (click, conversioni, fatturato generato dai clienti social).

Installazione

1. Scarica l’archivio dfsocialconnect.zip dal tuo account cliente su datafirefly.com.
2. Nel back office di PrestaShop, vai su Moduli > Gestore moduli > Carica un modulo e rilascia il ZIP.
3. Clicca su Installa. Il modulo crea 5 tabelle (ps_dfsc_identity, ps_dfsc_log, ps_dfsc_stats_daily, ps_dfsc_button_click, ps_dfsc_consent) e un tab BO nascosto AdminDfSocialConnect.
4. Clicca su Configura. Arrivi su una dashboard vuota: i primi dati appaiono non appena un utente clicca su un pulsante social.

Il modulo è compatibile con PrestaShop 8.0.0 a 9.99.99 e PHP 7.4 a 8.3. Nessuna dipendenza Composer esterna richiesta: un autoloader PSR-4 minimo è incluso.

Configurazione dei provider

Ogni provider richiede credenziali OAuth ottenute dalla sua console sviluppatore. Il modulo mostra l’URL di callback esatto da incollare in ogni console: è lo step più importante: qualsiasi errore di battitura causa un errore redirect_uri_mismatch.

Google OAuth2 / OpenID Connect

1. Vai su https://console.cloud.google.com/apis/credentials.
2. Crea o seleziona un progetto, poi clicca su Crea credenziali > ID client OAuth 2.0.
3. Tipo di applicazione: Applicazione web.
4. In URI di reindirizzamento autorizzati, incolla l’URL mostrato nel tab “Provider” della configurazione del modulo (formato: https://tuo-shop.com/module/dfsocialconnect/callback?provider=google).
5. Copia il Client ID e il Client Secret e incollali nel modulo.
6. Attiva il toggle “Google attivato”.

Apple Sign In

1. Vai su https://developer.apple.com/account/resources/identifiers/list (account sviluppatore Apple a pagamento richiesto).
2. Crea un Services ID (non un App ID). Annota il suo identifier: è il tuo Client ID.
3. Attiva Sign In with Apple su questo Services ID, configura il dominio del tuo shop e incolla l’URL di callback mostrato dal modulo (provider=apple) come Return URL.
4. In Keys, crea una nuova chiave con Sign In with Apple attivato. Scarica il file .p8: non potrai mai più recuperarlo.
5. Recupera il tuo Team ID (in alto a destra nella console Apple), il tuo Key ID (l’identifier della chiave creata al passo 4) e il contenuto completo del file .p8 (incluse le righe BEGIN PRIVATE KEY e END PRIVATE KEY).
6. Incolla i 4 campi nella configurazione del modulo (Services ID, Team ID, Key ID, contenuto .p8).
7. Attiva il toggle “Apple attivato”.

Il modulo firma il JWT client_secret in ES256 al volo e lo rigenera automaticamente ogni 5 mesi (la validità massima consentita da Apple è di 6 mesi). Nessuna rotazione manuale richiesta.

Facebook Login

1. Vai su https://developers.facebook.com/apps.
2. Crea una nuova app di tipo Consumatore.
3. Nella sezione Add products, aggiungi Facebook Login.
4. In Facebook Login > Settings, incolla l’URL di callback mostrato dal modulo (provider=facebook) in Valid OAuth Redirect URIs.
5. Recupera l’App ID e l’App Secret in Settings > Basic e incollali nel modulo.
6. Attiva il toggle “Facebook attivato”.

Il modulo utilizza l’API Graph v19.0 e attiva automaticamente appsecret_proof, che impedisce il riutilizzo di un access token rubato richiedendo una firma HMAC del secret dell’app.

Tab Comportamento

Questo tab controlla cosa accade una volta che il login social si completa con successo.

• Auto-link per email verificata — se l’email restituita dal provider è marcata come verificata e corrisponde a un account cliente esistente, il modulo collega automaticamente il provider a quell’account invece di crearne uno nuovo. Consigliato: ON.
• Importa avatar — scarica la foto del profilo in /img/dfsc/avatars/<id_customer>.<ext> (limite 2 MB, whitelist MIME JPEG/PNG/WebP). Sopravvive alla scadenza del CDN del provider.
• Buono di benvenuto — per ogni nuovo account creato tramite login social, il modulo crea una CartRule PrestaShop monouso intestata al cliente. Configura il prefisso (di default WELCOME), l’importo e la durata di validità.
• Gruppo cliente per provider — assegna un ID di gruppo PrestaShop a ciascun provider (Google / Apple / Facebook). Utile per segmentare le tue campagne marketing per origine.
• Opt-in newsletter di default — se attivato, il cliente creato viene marcato come iscritto (attivalo solo se il tuo processo include un double opt-in conforme al GDPR).
• Rate limiting — numero massimo di tentativi per IP in una finestra di 15 minuti. Di default: 30. Oltre, l’utente riceve il messaggio “Troppi tentativi”.
• Retention dei log — numero di giorni durante i quali conservare i log grezzi (ps_dfsc_log e ps_dfsc_button_click). Il rollup giornaliero (ps_dfsc_stats_daily) è conservato indefinitamente e alimenta la dashboard.

Tab Aspetto

Scegli il rendering visivo dei pulsanti:

• Stile — 5 varianti: rounded (di default, angoli 8 px), pill (completamente arrotondato), square (squadrato), ghost (trasparente con bordo), minimal (compatto).
• Modalità etichetta — 3 modalità: Continua con X (di default, neutra), Accedi con X (pagina di login), Iscriviti con X (pagina di registrazione).
• Mostra nella pagina di login e Mostra nella pagina di registrazione — toggle indipendenti.
• Widget Il mio account — mostra nell’area cliente una sezione “Account collegati” che permette di collegare o scollegare ciascun provider in qualsiasi momento (requisito GDPR).

Dashboard analitica

Il primo tab della configurazione aggrega le statistiche su una finestra mobile di 30 giorni per default (configurabile).

• 4 KPI cards — Accessi riusciti, Click sui pulsanti, Nuovi clienti creati, Errori.
• Curva temporale — accessi riusciti per giorno, segmentati per provider (Google blu, Apple nero, Facebook blu Meta).
• Ripartizione per provider — doughnut Chart.js con la percentuale di ciascun provider.
• Tasso di conversione per provider — click vs accesso riuscito. Permette di identificare un provider mal configurato (tasso anomalmente basso).
• Breakdown dispositivo e browser — bar chart aggregato sulla finestra.
• Heatmap giorno × ora — griglia 7 × 24 in 7 sfumature di blu. Identifica i picchi di uso per affinare le tue campagne.
• Penetrazione social — percentuale della tua base clienti che ha almeno un provider collegato.
• Fatturato generato dai clienti social — somma degli ordini pagati dei clienti creati tramite login social, calcolata da JOIN SQL su ps_orders.

Webhook CRM

A ogni accesso riuscito o account collegato, il modulo può inviare una richiesta HTTP POST a un URL a tua scelta, in modalità fire-and-forget (il tempo di risposta del tuo endpoint non impatta il tempo di accesso dell’utente).

• URL del webhook — endpoint HTTPS consigliato. Make, n8n, Zapier o il tuo stack interno.
• Segreto condiviso — utilizzato per firmare il payload tramite HMAC-SHA256. La firma è inviata nell’header X-Dfsc-Signature. Lato ricezione, ricalcola l’HMAC sul body grezzo per validare l’autenticità.

Payload di esempio:

{
  "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
}

GDPR e consenso

Il modulo è progettato per essere conforme al GDPR by design:

• A ogni login social, una riga viene inserita in ps_dfsc_consent con timestamp, IP, user agent e provider: è il tuo audit trail.
• Il widget “Account collegati” in Il mio account permette al cliente di scollegare un provider in qualsiasi momento.
• La disinstallazione del modulo rimuove pulitamente le 5 tabelle e tutte le chiavi di configurazione. Gli account cliente restano intatti.
• Nessun secret OAuth viaggia mai in chiaro: tutti gli scambi passano via HTTPS e il JWT Apple è firmato localmente con la tua chiave .p8.

Disinstallazione

Da Moduli > Gestore moduli, disinstalla il modulo. Il processo:

1. Rimuove le 5 tabelle ps_dfsc_*.
2. Rimuove il tab BO AdminDfSocialConnect.
3. Rimuove tutte le chiavi di configurazione DFSC_*.
4. I collegamenti social dei clienti vengono cancellati ma gli account cliente e i loro ordini restano intatti. Gli avatar nella cache di /img/dfsc/avatars/ vengono rimossi.

Risoluzione problemi

Errore “redirect_uri_mismatch” (Google) — l’URL incollato nella console Google non corrisponde esattamente a quello mostrato dal modulo. Verifica lo schema (https), il dominio (con o senza www) e il path completo. Nessun carattere finale (slash, spazio).

Errore “invalid_client” (Apple) — il tuo JWT client_secret non è valido. Cause frequenti: Team ID o Key ID errato, contenuto .p8 troncato (verifica le righe BEGIN/END PRIVATE KEY), o Services ID confuso con App ID.

Errore “Invalid OAuth access token signature” (Facebook) — il tuo App Secret è errato. Rigeneralo da Settings > Basic e incollalo di nuovo.

“Troppi tentativi, attendi” — il rate limiter è scattato. Attendi 15 minuti o aumenta la soglia in Comportamento.

Le statistiche non salgono — verifica che ps_dfsc_button_click riceva effettivamente righe (un click in modalità incognito dovrebbe bastare). Se non viene scritto nulla, il controller del front probabilmente non è raggiungibile: verifica le tue regole di rewriting URL.

Il buono di benvenuto non viene creato — verifica che la funzione sia attivata in Comportamento, che l’importo e il prefisso siano compilati, e che l’account cliente sia stato realmente creato (e non semplicemente collegato a uno esistente: l’auto-link non emette buono).