# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/dfsocialconnect/>
- Lingua: it
- Aggiornato il: 2026-06-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfsocialconnect/index.md), [en](https://www.datafirefly.com/en/documentation/dfsocialconnect/index.md), [es](https://www.datafirefly.com/es/documentation/dfsocialconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfsocialconnect/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsocialconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsocialconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsocialconnect/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## 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](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](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](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/.` (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).