DfSocialConnect SW: guia completo

O DfSocialConnect acrescenta ao Shopware 6 o início de sessão social com Google, Apple e Facebook, com um painel analítico completo integrado na administração. A extensão foi deliberadamente construída sem biblioteca JWT externa: a assinatura ES256 do client_secret da Apple é gerada nativamente em PHP através do openssl. Uma única base de código cobre o Shopware 6.6 e 6.7, sem build de storefront nem administração à medida impostos. Este guia cobre a instalação, a configuração por canal de venda de cada fornecedor, a apresentação dos botões, o painel, a ligação automática das contas, a segurança e a resolução de problemas.

Pré-requisitos

• Shopware 6.6.x ou 6.7.x (a 6.5 não é suportada, a extensão usa o AccountService::loginById introduzido na 6.6).
• PHP 8.2 ou mais recente, com a extensão openssl (usada para a assinatura ES256 e o HMAC do cookie de state).
• Um URL HTTPS válido para a sua loja: todos os fornecedores OAuth recusam URIs de redirecionamento em HTTP em produção.

Instalação

1. Transfira o DfSocialConnect-v1.0.1.zip a partir da sua conta DataFirefly.
2. Instale o ZIP em Administração → Extensões → As minhas extensões → Carregar extensão, ou copie a pasta descomprimida DfSocialConnect para custom/plugins/.
3. Ative a extensão e atualize as caches:

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

4. Na instalação, a extensão cria duas tabelas: df_social_account (identidades sociais ligadas aos clientes) e df_social_log (registo de eventos para o painel). Na desinstalação sem conservação dos dados, estas duas tabelas são eliminadas.

Configuração geral

Abra Extensões → As minhas extensões → DataFirefly Social Connect → ⋯ → Configurar. Todas as opções podem ter âmbito por canal de venda através do seletor nativo no topo da página: selecione um canal para lhe atribuir valores específicos, ou deixe «Todos os canais de venda» para valores comuns.

O cartão Geral contém:

• Estilo dos botões: «cor cheia» (por predefinição, nas cores oficiais), «contorno» (variante sóbria para temas minimalistas) ou «apenas ícone» (muito compacto, ideal em telemóvel).
• Ligar automaticamente por email verificado: se o fornecedor certificar o email e existir um cliente com esse endereço, a identidade social é associada a essa conta em vez de criar um duplicado. Ativo por predefinição.
• Ignorar o duplo opt-in: como os emails fornecidos pelo Google, pela Apple ou pelo Facebook já estão verificados, o duplo opt-in é contornado por predefinição.
• Newsletter no registo: acrescenta um sinal de opt-in de newsletter nas contas criadas por início de sessão social.
• Tentativas por hora (por IP): limiar de rate limiting do fluxo de autenticação. Predefinição 30; aumente se tiver muitos visitantes por trás do mesmo NAT.

Google Connect

1. Vá a console.cloud.google.com → APIs e serviços → Credenciais.
2. Crie um ID de cliente OAuth 2.0, do tipo Aplicação Web.
3. Em URIs de redirecionamento autorizados, acrescente:

   https://o-seu-dominio/df-social-connect/callback/google

   Em multicanal, acrescente uma linha por domínio de canal de venda.

4. Copie o Client ID e o Client Secret para o cartão Google Connect da configuração da extensão, e ative o interruptor Ativar o Google Connect.

O fluxo é OpenID Connect com PKCE S256, o scope pedido é openid email profile, e o nonce do id_token é validado do lado do servidor a cada retorno.

Apple Connect

A Apple é mais exigente na configuração, mas oferece a melhor experiência de utilizador em iOS e macOS.

1. Vá a developer.apple.com → Certificates, Identifiers and Profiles.
2. Crie um App ID com a capability Sign In with Apple.
3. Crie um Services ID (por exemplo com.a-sua-marca.web) ligado ao App ID. Na sua configuração:
   • Domains: o seu domínio (sem https://).
   • Return URLs: https://o-seu-dominio/df-social-connect/callback/apple.
4. Crie uma Key com o serviço Sign In with Apple, transfira o ficheiro AuthKey_XXXXX.p8 e anote o seu Key ID.
5. Obtenha o seu Team ID no canto superior direito do portal.
6. No cartão Apple Connect da extensão, preencha:
   • Services ID (por exemplo com.a-sua-marca.web),
   • Team ID,
   • Key ID,
   • Chave privada: cole o conteúdo completo do .p8, linhas BEGIN/END incluídas.

   Ative o interruptor Ativar o Sign in with Apple.

O client_secret JWT assinado em ES256 é gerado na hora a cada pedido a partir da chave .p8, sem cache: não há rotação a gerir.

Facebook Connect

1. Vá a developers.facebook.com → As minhas aplicações e crie uma App do tipo Consumer.
2. Acrescente o produto Facebook Login → Settings.
3. Em Valid OAuth Redirect URIs, acrescente:

   https://o-seu-dominio/df-social-connect/callback/facebook

4. Obtenha o App ID e o App Secret em Settings → Basic, e cole-os no cartão Facebook Connect da extensão. Ative o interruptor.

O módulo chama a Graph API v21.0 com appsecret_proof obrigatório (assinatura HMAC-SHA256 do token com o seu App Secret), o que o Facebook recomenda para qualquer aplicação em produção.

Apresentação dos botões no storefront

Assim que pelo menos um fornecedor está ativo e configurado, os botões aparecem automaticamente:

• na página /account/login, logo abaixo do formulário de início de sessão, precedidos do separador «ou continuar com»;
• na página /account/register, no mesmo sítio;
• na página de perfil do cliente (/account/profile), um bloco Inícios de sessão sociais lista as identidades já ligadas com um botão Desassociar por identidade, e propõe em complemento os fornecedores ainda disponíveis.

Não é necessária qualquer sobreposição de tema. Os templates Twig da extensão estendem os blocos page_account_login_login, page_account_register_content e page_account_profile_personal do Shopware. Se o seu tema personalizado já sobrepuser estes blocos e se esquecer de chamar {{ parent() }}, acrescente-o para reintegrar os botões.

Personalizar o estilo

Os botões são estilizados em Resources/app/storefront/src/scss/base.scss. São fornecidas três variantes de base (--default, --outline, --icon); para ir mais longe, sobreponha as classes .df-social-connect__btn--google, --apple e --facebook no seu tema.

Painel analítico

A administração expõe um módulo dedicado em Clientes → Social Connect. Quatro cartões filtráveis por período (7, 30 ou 90 dias) e por canal de venda:

• Visão geral: inícios de sessão, registos, contas ligadas, taxa de sucesso global, erros.
• Por fornecedor: barras de progresso nas cores oficiais de cada marca.
• Tendência diária: curva de várias séries em ApexCharts (uma linha por fornecedor).
• Atividade recente: os 25 últimos eventos com cliente, fornecedor, tipo de evento e mensagem.

O módulo está protegido por uma ACL de leitura dedicada: df_social_connect.viewer. Para dar acesso ao painel a um papel de utilizador, abra o seu perfil em Definições → Sistema → Utilizadores e permissões, e marque a permissão correspondente na categoria Clientes.

Ligação automática e antiduplicados

A cada início de sessão social, a extensão tenta três resoluções sucessivas:

1. Pesquisa direta pelo par (fornecedor, provider_user_id) em df_social_account. Encontrado: início de sessão imediato no cliente ligado.
2. Ligação por email verificado: se o fornecedor marcou o email como verificado e existir um cliente com esse endereço no canal de venda, a identidade social é associada a essa conta. Preserva o histórico de encomendas e o grupo de clientes.
3. Criação de conta: só em último recurso, é criado um novo cliente através do AccountService::loginById com uma palavra-passe aleatória nunca reutilizada, uma saudação neutra e uma morada mínima ligada ao país predefinido do canal de venda.

A ligação automática por email desativa-se por canal de venda na configuração geral, se preferir forçar a criação explícita a cada registo social.

Segurança

• State OAuth assinado com HMAC: proteção CSRF em todos os fluxos.
• PKCE S256 no Google: o code_verifier nunca sai do servidor.
• Nonce OIDC validado do lado do servidor no id_token do Google.
• appsecret_proof do Facebook: o token de utilizador não pode ser reproduzido a partir de outro cliente.
• IP em hash: os endereços IP dos eventos são transformados em hash antes de serem guardados em df_social_log.
• Rate limiting por IP, com limiar configurável por hora.
• Sanitização anti open-redirect: os URLs de retorno fornecidos pelo utilizador são verificados contra o domínio do canal de venda antes de qualquer redirecionamento.

Desinstalação

A partir de As minhas extensões, desative e desinstale a extensão. Se a opção Conservar os dados dos utilizadores estiver desativada, as duas tabelas df_social_account e df_social_log são eliminadas. As contas de cliente ficam intactas; apenas as ligações sociais e o registo de eventos são apagados.

FAQ e resolução de problemas

Nenhum botão aparece na página de início de sessão. Verifique que (a) pelo menos um fornecedor tem o interruptor ativo E as credenciais introduzidas na configuração; (b) está mesmo no canal de venda configurado; (c) o tema foi recompilado: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

A Apple devolve invalid_client. O client_secret JWT falhou do lado da Apple. Verifique o Services ID, o Team ID, o Key ID e que o conteúdo da chave .p8 inclui mesmo as linhas BEGIN e END. Uma hora de servidor desviada também aciona este erro, porque o JWT fica com um iat no futuro.

A Apple devolve um erro de state no retorno. Verifique que a sua loja é servida em HTTPS estrito (sem redirecionamento HTTP → HTTPS no callback) e que os seus cookies de terceiros não são bloqueados por um proxy frontal que reescreva o SameSite=None.

O Facebook devolve Invalid appsecret_proof provided. O App Secret introduzido não corresponde ao App ID. Regenere-o em Settings → Basic da sua App do Facebook e volte a colá-lo.

O painel está vazio apesar de ter havido inícios de sessão. Verifique o filtro de canal de venda no topo do painel: restringe todas as estatísticas. Selecione «Todos os canais de venda» para ver o agregado global.

Um utilizador tem duas contas: uma criada por formulário e outra pelo Google. A ligação automática por email estava desativada, ou o email da conta inicial não era exatamente igual ao devolvido pelo Google. Para fundir, elimine a conta mais recente e peça ao utilizador que volte a iniciar sessão pelo Google: a ligação automática vai associá-lo à conta conservada.

Compatível com o Shopware 6.5? Não. O AccountService::loginById foi introduzido na 6.6; esse mecanismo é central na extensão e não pode ser adaptado à 6.5 de forma limpa.