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

- Página: <https://www.datafirefly.com/pt/documentation/dfsocialconnect-sw/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfsocialconnect-sw/index.md), [en](https://www.datafirefly.com/en/documentation/dfsocialconnect-sw-2/index.md), [es](https://www.datafirefly.com/es/documentation/dfsocialconnect-sw-3/index.md), [de](https://www.datafirefly.com/de/documentation/dfsocialconnect-sw-4/index.md), [it](https://www.datafirefly.com/it/documentation/dfsocialconnect-sw-5/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsocialconnect-sw/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsocialconnect-sw/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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.

O Apple Sign In exige uma configuração séria do lado do Apple Developer (Services ID, Team ID, Key ID, chave .p8) e um domínio HTTPS válido. Sem estes elementos, só o Google e o Facebook ficarão operacionais. O módulo funciona igualmente bem com um único fornecedor ativo.

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

No Shopware 6.7, a nova administração Meteor carrega automaticamente os módulos das extensões sem build de administração. Na 6.6, se o menu «Social Connect» em Clientes não aparecer depois da instalação, execute `bin/console administration:build` e limpe as caches do navegador.

## 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: Ative o interruptor **Ativar o Sign in with Apple**.
   - **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.

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.

**A armadilha do callback Apple form_post.** Quando se pede o scope `name email`, a Apple devolve o callback em POST cross-site, o que impede o cookie de sessão SameSite Lax de ser devolvido. A maioria das integrações parte-se nesse momento. O DfSocialConnect coloca em paralelo um cookie de state assinado com HMAC em SameSite None, e revalida através desse cookie quando a sessão não está disponível. Não é necessária qualquer configuração da sua parte, mas isso pressupõe que a sua loja é servida em HTTPS estrito (os cookies SameSite=None exigem `Secure`).

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