DataFirefly Social Connect — Documentación

Presentación

DataFirefly Social Connect añade a PrestaShop 8 y 9 tres botones de inicio de sesión social (Google, Apple, Facebook) acompañados de un panel de análisis completo. El módulo no solo autentica: mide la conversión, genera automáticamente bonos de bienvenida, alimenta tu CRM mediante un webhook firmado y se mantiene 100% conforme con el RGPD.

El objetivo es doble: eliminar la fricción de registro (un clic en lugar de un formulario) y medir el impacto real en el negocio (clics, conversiones, facturación generada por los clientes sociales).

Instalación

1. Descarga el archivo dfsocialconnect.zip desde tu cuenta de cliente en datafirefly.com.
2. En el back office de PrestaShop, ve a Módulos > Gestor de módulos > Subir un módulo y suelta el ZIP.
3. Haz clic en Instalar. El módulo crea 5 tablas (ps_dfsc_identity, ps_dfsc_log, ps_dfsc_stats_daily, ps_dfsc_button_click, ps_dfsc_consent) y una pestaña BO oculta AdminDfSocialConnect.
4. Haz clic en Configurar. Llegarás a un panel vacío: los primeros datos aparecerán en cuanto un usuario haga clic en un botón social.

El módulo es compatible con PrestaShop 8.0.0 a 9.99.99 y PHP 7.4 a 8.3. No requiere ninguna dependencia Composer externa: incluye un autoloader PSR-4 mínimo.

Configuración de los proveedores

Cada proveedor requiere credenciales OAuth obtenidas desde su consola de desarrollador. El módulo muestra la URL de callback exacta a copiar en cada consola — este es el paso más importante: cualquier error tipográfico provoca un error redirect_uri_mismatch.

Google OAuth2 / OpenID Connect

1. Ve a https://console.cloud.google.com/apis/credentials.
2. Crea o selecciona un proyecto, después haz clic en Crear credenciales > ID de cliente OAuth 2.0.
3. Tipo de aplicación: Aplicación web.
4. En URI de redirección autorizados, pega la URL mostrada en la pestaña «Proveedores» de la configuración del módulo (formato: https://tu-tienda.com/module/dfsocialconnect/callback?provider=google).
5. Copia el Client ID y el Client Secret y pégalos en el módulo.
6. Activa el toggle «Google activado».

Apple Sign In

1. Ve a https://developer.apple.com/account/resources/identifiers/list (se requiere cuenta de desarrollador Apple de pago).
2. Crea un Services ID (no un App ID). Anota su identificador: ese es tu Client ID.
3. Activa Sign In with Apple en este Services ID, configura el dominio de tu tienda y pega la URL de callback mostrada por el módulo (provider=apple) como Return URL.
4. En Keys, crea una nueva clave con Sign In with Apple activado. Descarga el archivo .p8: no podrás recuperarlo nunca más.
5. Obtén tu Team ID (esquina superior derecha de la consola Apple), tu Key ID (el identificador de la clave creada en el paso 4) y el contenido completo del archivo .p8 (incluidas las líneas BEGIN PRIVATE KEY y END PRIVATE KEY).
6. Pega los 4 campos en la configuración del módulo (Services ID, Team ID, Key ID, contenido .p8).
7. Activa el toggle «Apple activado».

El módulo firma el JWT client_secret en ES256 al vuelo y lo regenera automáticamente cada 5 meses (la validez máxima permitida por Apple es de 6 meses). No requiere rotación manual.

Facebook Login

1. Ve a https://developers.facebook.com/apps.
2. Crea una nueva app de tipo Consumidor.
3. En la sección Add products, añade Facebook Login.
4. En Facebook Login > Settings, pega la URL de callback mostrada por el módulo (provider=facebook) en Valid OAuth Redirect URIs.
5. Obtén el App ID y el App Secret en Settings > Basic y pégalos en el módulo.
6. Activa el toggle «Facebook activado».

El módulo utiliza la API Graph v19.0 y activa automáticamente appsecret_proof, que impide la reutilización de un access token robado al exigir una firma HMAC del secreto de la app.

Pestaña Comportamiento

Esta pestaña controla qué ocurre una vez que el login social se completa con éxito.

• Auto-vinculación por email verificado — si el email devuelto por el proveedor está marcado como verificado y coincide con una cuenta de cliente existente, el módulo vincula automáticamente el proveedor a esa cuenta en lugar de crear una nueva. Recomendado: ON.
• Importar avatar — descarga la foto de perfil en /img/dfsc/avatars/<id_customer>.<ext> (límite 2 MB, lista blanca MIME JPEG/PNG/WebP). Sobrevive a la expiración de los CDN del proveedor.
• Bono de bienvenida — para cada cuenta nueva creada mediante login social, el módulo crea una CartRule de PrestaShop de un solo uso a nombre del cliente. Configura el prefijo (por defecto WELCOME), el importe y la duración de validez.
• Grupo de cliente por proveedor — asigna un ID de grupo de PrestaShop a cada proveedor (Google / Apple / Facebook). Útil para segmentar tus campañas de marketing por origen.
• Opt-in de newsletter por defecto — si está activado, el cliente creado se marca como suscrito (solo actívalo si tu proceso incluye un doble opt-in conforme con el RGPD).
• Rate limiting — número máximo de intentos por IP en una ventana de 15 minutos. Por defecto: 30. Más allá, el usuario recibe un mensaje «Demasiados intentos».
• Retención de logs — número de días durante los cuales se conservan los logs brutos (ps_dfsc_log y ps_dfsc_button_click). El rollup diario (ps_dfsc_stats_daily) se conserva indefinidamente y alimenta el panel.

Pestaña Apariencia

Elige la representación visual de los botones:

• Estilo — 5 variantes: rounded (por defecto, esquinas 8 px), pill (totalmente redondeado), square (angular), ghost (transparente con borde), minimal (compacto).
• Modo de etiqueta — 3 modos: Continuar con X (por defecto, neutro), Iniciar sesión con X (página de login), Registrarse con X (página de registro).
• Mostrar en página de login y Mostrar en página de registro — toggles independientes.
• Widget Mi cuenta — muestra en el área de cliente una sección «Cuentas conectadas» que permite vincular o desvincular cada proveedor en cualquier momento (requisito RGPD).

Panel de análisis

La primera pestaña de la configuración agrega las estadísticas en una ventana móvil de 30 días por defecto (configurable).

• 4 KPI cards — Inicios de sesión exitosos, Clics en botones, Nuevos clientes creados, Fallos.
• Curva temporal — inicios de sesión exitosos por día, segmentados por proveedor (Google azul, Apple negro, Facebook azul Meta).
• Reparto por proveedor — doughnut Chart.js con el porcentaje de cada proveedor.
• Tasa de conversión por proveedor — clic vs inicio de sesión exitoso. Permite identificar un proveedor mal configurado (tasa anormalmente baja).
• Breakdown de dispositivo y navegador — gráfico de barras agregado en la ventana.
• Heatmap día × hora — cuadrícula 7 × 24 en 7 tonos de azul. Identifica los picos de uso para ajustar tus campañas.
• Penetración social — porcentaje de tu base de clientes que tiene al menos un proveedor vinculado.
• Facturación generada por clientes sociales — suma de los pedidos pagados de los clientes creados mediante login social, calculada por JOIN SQL sobre ps_orders.

Webhook CRM

En cada inicio de sesión exitoso o cuenta vinculada, el módulo puede enviar una petición HTTP POST a una URL de tu elección, en modo fire-and-forget (el tiempo de respuesta de tu endpoint no impacta el tiempo de inicio de sesión del usuario).

• URL del webhook — se recomienda endpoint HTTPS. Make, n8n, Zapier o tu stack interno.
• Secreto compartido — se utiliza para firmar el payload mediante HMAC-SHA256. La firma se envía en la cabecera X-Dfsc-Signature. En el lado receptor, recalcula el HMAC sobre el body bruto para validar la autenticidad.

Payload de ejemplo:

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

RGPD y consentimiento

El módulo está diseñado para ser conforme con el RGPD by design:

• En cada login social, se inserta una fila en ps_dfsc_consent con timestamp, IP, user agent y proveedor: es tu pista de auditoría.
• El widget «Cuentas conectadas» en Mi cuenta permite al cliente desvincular un proveedor en cualquier momento.
• La desinstalación del módulo elimina limpiamente las 5 tablas y todas las claves de configuración. Las cuentas de cliente quedan intactas.
• Ningún secreto OAuth viaja nunca en claro: todos los intercambios pasan por HTTPS y el JWT de Apple se firma localmente con tu clave .p8.

Desinstalación

Desde Módulos > Gestor de módulos, desinstala el módulo. El proceso:

1. Elimina las 5 tablas ps_dfsc_*.
2. Elimina la pestaña BO AdminDfSocialConnect.
3. Elimina todas las claves de configuración DFSC_*.
4. Los enlaces sociales de los clientes se borran pero las cuentas de cliente y sus pedidos quedan intactos. Los avatares cacheados en /img/dfsc/avatars/ se eliminan.

Resolución de problemas

Error «redirect_uri_mismatch» (Google) — la URL pegada en la consola de Google no coincide exactamente con la mostrada por el módulo. Comprueba el esquema (https), el dominio (con o sin www) y la ruta completa. Sin caracteres finales (slash, espacio).

Error «invalid_client» (Apple) — tu JWT client_secret no es válido. Causas frecuentes: Team ID o Key ID incorrecto, contenido .p8 truncado (comprueba las líneas BEGIN/END PRIVATE KEY), o Services ID confundido con App ID.

Error «Invalid OAuth access token signature» (Facebook) — tu App Secret es incorrecto. Regenéralo desde Settings > Basic y pégalo de nuevo.

«Demasiados intentos, por favor espera» — activación del rate limiter. Espera 15 minutos o aumenta el umbral en Comportamiento.

Las estadísticas no suben — comprueba que ps_dfsc_button_click recibe efectivamente filas (un clic en modo incógnito debería bastar). Si no se escribe nada, el controlador del front probablemente no es accesible: comprueba tus reglas de reescritura de URL.

El bono de bienvenida no se crea — comprueba que la función está activada en Comportamiento, que el importe y el prefijo están rellenados, y que la cuenta de cliente realmente se creó (y no simplemente se vinculó a una existente: la auto-vinculación no emite bono).