DfSocialConnect SW — Guía completa

DfSocialConnect añade a Shopware 6 el login social con Google, Apple y Facebook, con un panel analítico completo integrado en la administración. El plugin está deliberadamente construido sin biblioteca JWT externa: la firma ES256 del client_secret de Apple se genera nativamente en PHP mediante openssl. Un único codebase cubre Shopware 6.6 y 6.7, sin build forzado del storefront ni de la administración. Esta guía cubre la instalación, la configuración por canal de venta de cada proveedor, la visualización de los botones, el panel, la vinculación automática de cuentas, la seguridad y la resolución de problemas.

Requisitos previos

• Shopware 6.6.x o 6.7.x (6.5 no es compatible; el plugin usa AccountService::loginById, introducido en 6.6).
• PHP 8.2 o superior, con la extensión openssl (usada para la firma ES256 y el HMAC del cookie de state).
• Una URL HTTPS válida para su tienda: todos los proveedores OAuth rechazan URI de redirección en HTTP en producción.

Instalación

1. Descargue DfSocialConnect-v1.0.1.zip desde su cuenta DataFirefly.
2. Instale el ZIP mediante Administración → Extensiones → Mis extensiones → Cargar extensión, o copie la carpeta descomprimida DfSocialConnect en custom/plugins/.
3. Active el plugin y refresque las cachés:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfSocialConnect
   bin/console cache:clear

4. Al instalar, el plugin crea dos tablas: df_social_account (identidades sociales vinculadas a clientes) y df_social_log (registro de eventos para el panel). Al desinstalar sin conservar datos, ambas tablas se eliminan.

Configuración general

Abra Extensiones → Mis extensiones → DataFirefly Social Connect → ⋯ → Configurar. Todas las opciones se pueden delimitar al canal de venta mediante el selector nativo en la parte superior: elija un canal para asignarle valores específicos, o deje «Todos los canales de venta» para valores comunes.

La tarjeta General contiene:

• Estilo de los botones: «color completo» (por defecto, con los tonos oficiales), «contorno» (variante sobria para temas minimalistas) o «solo icono» (muy compacto, ideal en móvil).
• Vincular automáticamente por email verificado: si el proveedor certifica el email y ya existe un cliente con esa dirección, la identidad social se vincula a esa cuenta en lugar de crear un duplicado. Activado por defecto.
• Ignorar el doble opt-in: dado que los emails de Google, Apple o Facebook ya están verificados, el doble opt-in se omite por defecto.
• Newsletter al registrarse: añade un flag de opt-in newsletter a las cuentas creadas por login social.
• Intentos por hora (por IP): umbral de limitación de tasa del flujo de autenticación. Por defecto 30; auméntelo si muchos visitantes comparten un NAT.

Google Connect

1. Vaya a console.cloud.google.com → API y servicios → Credenciales.
2. Cree un ID de cliente OAuth 2.0, tipo Aplicación Web.
3. En URI de redireccionamiento autorizadas, añada:

   https://su-dominio/df-social-connect/callback/google

   Para un multi-canal, añada una línea por dominio de canal de venta.

4. Pegue Client ID y Client Secret en la tarjeta Google Connect de la configuración del plugin, y active el toggle Activar Google Connect.

El flujo es OpenID Connect con PKCE S256, el scope solicitado es openid email profile, y el nonce del id_token se valida del lado del servidor en cada retorno.

Apple Connect

Apple es el más exigente de configurar pero ofrece la mejor experiencia en iOS y macOS.

1. Vaya a developer.apple.com → Certificates, Identifiers and Profiles.
2. Cree un App ID con la capability Sign In with Apple.
3. Cree un Services ID (por ejemplo com.su-marca.web) vinculado al App ID. En su configuración:
   • Domains: su dominio (sin https://).
   • Return URLs: https://su-dominio/df-social-connect/callback/apple.
4. Cree una Key con el servicio Sign In with Apple activado, descargue el archivo AuthKey_XXXXX.p8 y anote su Key ID.
5. Obtenga su Team ID en la esquina superior derecha del portal.
6. En la tarjeta Apple Connect del plugin, rellene:
   • Services ID (ej. com.su-marca.web),
   • Team ID,
   • Key ID,
   • Clave privada: pegue el contenido completo del .p8, incluyendo las líneas BEGIN/END.

   Active el toggle Activar Sign in with Apple.

El JWT client_secret firmado en ES256 se genera al vuelo en cada petición a partir de la clave .p8, sin caché: no hay rotación que gestionar.

Facebook Connect

1. Vaya a developers.facebook.com → Mis aplicaciones y cree una App de tipo Consumer.
2. Añada el producto Facebook Login → Settings.
3. En Valid OAuth Redirect URIs, añada:

   https://su-dominio/df-social-connect/callback/facebook

4. Obtenga App ID y App Secret en Settings → Basic, y péguelos en la tarjeta Facebook Connect del plugin. Active el toggle.

El módulo llama a la Graph API v21.0 con appsecret_proof obligatorio (firma HMAC-SHA256 del token con su App Secret), lo que Facebook recomienda para cualquier app en producción.

Visualización de los botones en el storefront

Una vez activado y configurado al menos un proveedor, los botones aparecen automáticamente:

• en la página /account/login, justo debajo del formulario de login, precedidos por un separador «o continuar con»;
• en la página /account/register, en la misma posición;
• en la página de perfil del cliente (/account/profile), un bloque Conexiones sociales lista las identidades ya vinculadas con un botón Desconectar por identidad, y muestra los proveedores restantes como botones para vincular.

No se necesita sobrescribir el tema. Las plantillas Twig del plugin extienden los bloques page_account_login_login, page_account_register_content y page_account_profile_personal de Shopware. Si su tema personalizado ya sobrescribe estos bloques y olvida llamar a {{ parent() }}, añádalo para reincluir los botones.

Personalizar el estilo

Los botones tienen sus estilos en Resources/app/storefront/src/scss/base.scss. Se suministran tres variantes base (--default, --outline, --icon); para personalizaciones avanzadas, sobrescriba las clases .df-social-connect__btn--google, --apple y --facebook en su tema.

Panel analítico

La administración expone un módulo dedicado bajo Clientes → Social Connect. Cuatro tarjetas filtrables por período (7, 30 o 90 días) y por canal de venta:

• Vista general: logins, registros, vinculaciones, tasa global de éxito, errores.
• Por proveedor: barras de progreso con los colores oficiales de cada marca.
• Tendencia diaria: curva multi-serie ApexCharts (una línea por proveedor).
• Actividad reciente: los 25 últimos eventos con cliente, proveedor, tipo de evento y mensaje.

El módulo está protegido por una ACL viewer dedicada: df_social_connect.viewer. Para dar acceso al panel a un rol de usuario, abra su perfil en Configuración → Sistema → Usuarios y permisos y marque el permiso correspondiente en la categoría Clientes.

Vinculación automática y evitación de duplicados

En cada login social, el plugin ejecuta tres niveles de resolución:

1. Lookup directo por par (proveedor, provider_user_id) en df_social_account. Encontrado: login inmediato en el cliente vinculado.
2. Vinculación por email verificado: si el proveedor marcó el email como verificado y existe un cliente con esa dirección en el canal de venta, la identidad social se vincula a esa cuenta. Preserva el historial de pedidos y el grupo de cliente.
3. Creación de cuenta: solo como último recurso, se crea un nuevo cliente vía AccountService::loginById con una contraseña aleatoria nunca reutilizada, un saludo neutro y una dirección mínima vinculada al país por defecto del canal de venta.

La vinculación automática por email se puede desactivar por canal de venta en la configuración general si prefiere forzar la creación explícita en cada registro social.

Seguridad

• State OAuth firmado HMAC: protección CSRF en todos los flujos.
• PKCE S256 en Google: el code_verifier nunca sale del servidor.
• Nonce OIDC validado del lado del servidor en el id_token de Google.
• appsecret_proof Facebook: el token de usuario no puede ser reusado desde otro cliente.
• IP hasheada: las direcciones IP de los eventos se hashean antes de almacenarse en df_social_log.
• Limitación de tasa por IP, umbral configurable por hora.
• Sanitización anti open-redirect: las URLs de retorno proporcionadas por el usuario se verifican contra el dominio del canal de venta antes de cualquier redirección.

Desinstalación

Desde Mis extensiones, desactive y desinstale el plugin. Si la opción Conservar los datos de usuario está desactivada, las dos tablas df_social_account y df_social_log se eliminan. Las cuentas de cliente permanecen intactas: solo se borran los vínculos sociales y el registro de eventos.

FAQ y resolución de problemas

No aparece ningún botón en la página de login. Verifique que (a) al menos un proveedor tiene su toggle activado Y sus credenciales rellenadas; (b) está en el canal de venta configurado; (c) el tema ha sido recompilado: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple devuelve invalid_client. La validación del client_secret JWT falló. Verifique Services ID, Team ID, Key ID y que el contenido del .p8 incluya las líneas BEGIN y END. Un reloj del servidor desfasado también provoca este error porque el iat del JWT acaba en el futuro.

Apple devuelve un error de state al retorno. Confirme que su tienda se sirve por HTTPS estricto (sin redirección HTTP → HTTPS en el callback) y que ningún proxy frontal elimina o reescribe el atributo SameSite=None en las cabeceras Set-Cookie salientes.

Facebook devuelve Invalid appsecret_proof provided. El App Secret introducido no coincide con el App ID. Regenérelo desde Settings → Basic de su App Facebook y vuelva a pegarlo.

El panel está vacío aunque ha habido logins. Compruebe el filtro de canal de venta en la parte superior del panel: delimita todas las estadísticas. Elija «Todos los canales de venta» para ver el agregado global.

Un usuario tiene dos cuentas: una creada por formulario, otra por Google. La vinculación automática por email estaba desactivada, o el email de la cuenta original no era estrictamente idéntico al devuelto por Google. Para fusionarlas, elimine la cuenta más reciente y pida al usuario que vuelva a conectarse con Google: la vinculación automática asociará la identidad a la cuenta conservada.

¿Compatible con Shopware 6.5? No. AccountService::loginById se introdujo en 6.6; este mecanismo es central para el plugin y no puede ser retroportado limpiamente.