DfSocialConnect SW — Guide complet

DfSocialConnect ajoute à Shopware 6 la connexion sociale Google, Apple et Facebook, avec un dashboard analytique complet intégré à l’administration. Le plugin est volontairement bâti sans bibliothèque JWT externe : la signature ES256 du client_secret Apple est générée nativement en PHP via openssl. Un seul codebase couvre Shopware 6.6 et 6.7, sans build storefront ni administration sur mesure imposés. Ce guide couvre l’installation, la configuration par canal de vente de chaque fournisseur, l’affichage des boutons, le dashboard, la liaison automatique des comptes, la sécurité et le dépannage.

Prérequis

• Shopware 6.6.x ou 6.7.x (la 6.5 n’est pas supportée, le plugin utilise AccountService::loginById introduit en 6.6).
• PHP 8.2 ou plus récent, avec l’extension openssl (utilisée pour la signature ES256 et le HMAC du cookie de state).
• Une URL HTTPS valide pour votre boutique : tous les fournisseurs OAuth refusent les URI de redirection en HTTP en production.

Installation

1. Téléchargez DfSocialConnect-v1.0.1.zip depuis votre compte DataFirefly.
2. Installez le ZIP via Administration → Extensions → Mes extensions → Charger l’extension, ou copiez le dossier décompressé DfSocialConnect dans custom/plugins/.
3. Activez le plugin et rafraîchissez les caches :

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

4. À l’installation, le plugin crée deux tables : df_social_account (identités sociales liées aux clients) et df_social_log (journal d’événements pour le dashboard). À la désinstallation sans conservation des données, ces deux tables sont supprimées.

Configuration générale

Ouvrez Extensions → Mes extensions → DataFirefly Social Connect → ⋯ → Configurer. Toutes les options sont scopables au canal de vente via le sélecteur natif en haut de la page : sélectionnez un canal pour lui attribuer des valeurs spécifiques, ou laissez « Tous les canaux de vente » pour des valeurs communes.

La carte Général contient :

• Style des boutons : « pleine couleur » (par défaut, aux teintes officielles), « contour » (variante sobre pour les thèmes minimalistes) ou « icône seule » (très compact, idéal en mobile).
• Lier automatiquement par email vérifié : si le fournisseur certifie l’email et qu’un client existe avec cette adresse, l’identité sociale est rattachée à ce compte au lieu d’en créer un doublon. Activé par défaut.
• Ignorer le double opt-in : les emails fournis par Google, Apple ou Facebook étant déjà vérifiés, le double opt-in est court-circuité par défaut.
• Newsletter à l’inscription : ajoute un flag d’opt-in newsletter sur les comptes créés via une connexion sociale.
• Tentatives par heure (par IP) : seuil de rate limiting du flow d’authentification. Défaut 30, augmentez si vous avez beaucoup de visiteurs derrière un même NAT.

Google Connect

1. Allez sur console.cloud.google.com → APIs et services → Identifiants.
2. Créez un ID client OAuth 2.0, type Application Web.
3. Dans URI de redirection autorisées, ajoutez :

   https://votre-domaine/df-social-connect/callback/google

   Pour un multi-canal, ajoutez une ligne par domaine de canal de vente.

4. Copiez Client ID et Client Secret dans la carte Google Connect de la configuration du plugin, et activez le toggle Activer Google Connect.

Le flow est OpenID Connect avec PKCE S256, le scope demandé est openid email profile, et le nonce de l’id_token est validé côté serveur à chaque retour.

Apple Connect

Apple est plus exigeant à configurer mais offre la meilleure expérience utilisateur sur iOS et macOS.

1. Allez sur developer.apple.com → Certificates, Identifiers and Profiles.
2. Créez un App ID avec la capability Sign In with Apple.
3. Créez un Services ID (par exemple com.votre-marque.web) lié à l’App ID. Dans sa configuration :
   • Domains : votre domaine (sans https://).
   • Return URLs : https://votre-domaine/df-social-connect/callback/apple.
4. Créez une Key avec le service Sign In with Apple, téléchargez le fichier AuthKey_XXXXX.p8 et notez son Key ID.
5. Récupérez votre Team ID en haut à droite du portail.
6. Dans la carte Apple Connect du plugin, renseignez :
   • Services ID (ex. com.votre-marque.web),
   • Team ID,
   • Key ID,
   • Clé privée : collez le contenu complet du .p8, lignes BEGIN/END comprises.

   Activez le toggle Activer Sign in with Apple.

Le client_secret JWT signé en ES256 est généré à la volée à chaque requête à partir de la clé .p8, sans cache : aucune rotation à gérer.

Facebook Connect

1. Allez sur developers.facebook.com → Mes applications et créez une App de type Consumer.
2. Ajoutez le produit Facebook Login → Settings.
3. Dans Valid OAuth Redirect URIs, ajoutez :

   https://votre-domaine/df-social-connect/callback/facebook

4. Récupérez App ID et App Secret dans Settings → Basic, et collez-les dans la carte Facebook Connect du plugin. Activez le toggle.

Le module appelle la Graph API v21.0 avec appsecret_proof obligatoire (signature HMAC-SHA256 du token avec votre App Secret), ce que Facebook recommande pour toute application en production.

Affichage des boutons côté storefront

Une fois au moins un fournisseur activé et configuré, les boutons apparaissent automatiquement :

• sur la page /account/login, juste sous le formulaire de connexion, précédés du séparateur « ou continuer avec » ;
• sur la page /account/register, au même endroit ;
• dans la page profil du client (/account/profile), un bloc Connexions sociales liste les identités déjà liées avec un bouton Dissocier par identité, et propose en complément les fournisseurs encore disponibles.

Aucune surcharge de thème n’est nécessaire. Les templates Twig du plugin étendent les blocs page_account_login_login, page_account_register_content et page_account_profile_personal de Shopware. Si votre thème personnalisé surcharge déjà ces blocs et oublie d’appeler {{ parent() }}, ajoutez-le pour réintégrer les boutons.

Personnaliser le style

Les boutons sont stylés via Resources/app/storefront/src/scss/base.scss. Trois variantes sont fournies de base (--default, --outline, --icon) ; pour aller plus loin, surchargez les classes .df-social-connect__btn--google, --apple et --facebook dans votre thème.

Dashboard analytique

L’administration expose un module dédié sous Clients → Social Connect. Quatre cartes filtrables par période (7, 30 ou 90 jours) et par canal de vente :

• Vue d’ensemble : connexions, inscriptions, comptes liés, taux de réussite global, erreurs.
• Par fournisseur : barres de progression aux couleurs officielles de chaque marque.
• Tendance quotidienne : courbe multi-séries ApexCharts (une ligne par fournisseur).
• Activité récente : 25 derniers événements avec client, fournisseur, type d’événement et message.

Le module est protégé par une ACL viewer dédiée : df_social_connect.viewer. Pour donner accès au dashboard à un rôle utilisateur, ouvrez son profil sous Réglages → Système → Utilisateurs et permissions, et cochez la permission correspondante dans la catégorie Clients.

Liaison automatique et anti-doublon

À chaque connexion sociale, le plugin tente trois résolutions successives :

1. Lookup direct par paire (fournisseur, provider_user_id) dans df_social_account. Trouvé : login immédiat sur le client lié.
2. Liaison par email vérifié : si le fournisseur a marqué l’email comme vérifié et qu’un client existe avec cette adresse dans le canal de vente, l’identité sociale est rattachée à ce compte. Préserve l’historique de commandes et le groupe client.
3. Création de compte : en dernier recours uniquement, un nouveau client est créé via AccountService::loginById avec un mot de passe aléatoire jamais réutilisé, une salutation neutre et une adresse minimale liée au pays par défaut du canal de vente.

La liaison automatique par email se désactive par canal de vente dans la configuration générale, si vous préférez forcer la création explicite à chaque inscription sociale.

Sécurité

• State OAuth signé HMAC : protection CSRF sur tous les flows.
• PKCE S256 sur Google : le code_verifier ne quitte jamais le serveur.
• Nonce OIDC validé côté serveur sur l’id_token Google.
• appsecret_proof Facebook : le token utilisateur ne peut pas être rejoué depuis un autre client.
• IP hachée : les adresses IP des événements sont hachées avant stockage dans df_social_log.
• Rate limiting par IP, seuil configurable par heure.
• Sanitisation anti open-redirect : les URL de retour fournies par l’utilisateur sont vérifiées contre le domaine du canal de vente avant toute redirection.

Désinstallation

Depuis Mes extensions, désactivez puis désinstallez le plugin. Si l’option Conserver les données utilisateurs est désactivée, les deux tables df_social_account et df_social_log sont supprimées. Les comptes clients restent intacts — seuls les liens sociaux et le journal d’événements sont effacés.

FAQ et dépannage

Aucun bouton ne s’affiche sur la page login. Vérifiez que (a) au moins un fournisseur a son toggle activé ET ses identifiants saisis dans la configuration ; (b) que vous êtes bien sur le canal de vente configuré ; (c) que le thème a été recompilé : bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple renvoie invalid_client. Le client_secret JWT a échoué côté Apple. Vérifiez Services ID, Team ID, Key ID et que le contenu de la clé .p8 inclut bien les lignes BEGIN et END. Une heure serveur dérivée déclenche aussi cette erreur car le JWT a un iat dans le futur.

Apple renvoie une erreur de state au retour. Vérifiez que votre boutique est servie en HTTPS strict (pas de redirection HTTP → HTTPS sur le callback) et que vos cookies tiers ne sont pas bloqués par un proxy frontal qui réécrirait SameSite=None.

Facebook renvoie Invalid appsecret_proof provided. Le App Secret saisi ne correspond pas à l’App ID. Régénérez-le depuis Settings → Basic de votre App Facebook et recollez-le.

Le dashboard est vide alors qu’il y a eu des connexions. Vérifiez le filtre canal de vente en haut du dashboard : il restreint toutes les statistiques. Sélectionnez « Tous les canaux de vente » pour voir l’agrégat global.

Un utilisateur a deux comptes : l’un créé par formulaire, l’autre par Google. La liaison automatique par email était désactivée, ou l’email du compte initial n’était pas exactement identique à celui retourné par Google. Pour fusionner, supprimez le compte le plus récent puis demandez à l’utilisateur de se reconnecter via Google : la liaison automatique le rattachera au compte conservé.

Compatible Shopware 6.5 ? Non. AccountService::loginById a été introduit en 6.6 ; ce mécanisme est central au plugin et ne peut pas être backporté proprement.