# DataFirefly Social Connect: guia completo

> Guia completo de instalação, configuração e utilização do DataFirefly Social Connect: início de sessão social através de Google, Apple, Facebook, Microsoft, LinkedIn e X para WooCommerce, com estatísticas, atribuição das encomendas, teste A/B e antifraude.

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

## Apresentação

O DataFirefly Social Connect acrescenta à sua loja WooCommerce um início de sessão social num clique através de seis fornecedores (Google, Apple, Facebook, Microsoft, LinkedIn e X), um painel estatístico completo, a atribuição das encomendas ao fornecedor de origem, um teste A/B dos botões, um sistema antifraude e a conformidade RGPD nativa.

O plugin não usa qualquer biblioteca de CDN externa: os gráficos do painel são desenhados em canvas HTML5 nativo, e os fluxos OAuth 2.0 e OpenID Connect são implementados diretamente no módulo (verificação completa das assinaturas JWKS no Google One-Tap, assinatura ES256 em tempo real na Apple, reforço com `appsecret_proof` no Facebook, PKCE S256 no X).

**Requisitos**: WordPress 6.2 ou superior, WooCommerce 7.0 ou superior, PHP 8.0 ou superior. A compatibilidade com o HPOS e com os blocos de checkout do WooCommerce é declarada pelo plugin na ativação.

## Instalação

1. Descarregue o ficheiro ZIP do plugin a partir da sua área de cliente DataFirefly.
2. No WordPress, vá a _Plugins → Adicionar → Carregar plugin_.
3. Selecione o ZIP e clique em _Instalar agora_.
4. Clique em _Ativar_. O WooCommerce tem de estar ativo no momento da ativação, caso contrário o plugin recusa instalar-se.
5. Aparece um novo menu _Social Connect_ na barra lateral de administração, com duas subpáginas: _Estatísticas_ e _Definições_.

Na ativação, são criadas duas tabelas SQL: `wp_dfsc_connections` (contas ligadas) e `wp_dfsc_events` (registo de eventos para as estatísticas). As opções predefinidas são gravadas em `dfsc_settings`.

## Configuração dos fornecedores

Cada fornecedor tem o seu próprio cartão no separador _Fornecedores_ das definições. Em cada um, encontra no topo do cartão o **URI de redirecionamento** a copiar para a consola do fornecedor. É este parâmetro que autoriza o seu site a receber o retorno da autenticação.

### Google (com One-Tap)

1. Vá à [Google Cloud Console](https://console.cloud.google.com/) e crie (ou selecione) um projeto.
2. Em _APIs & Services → OAuth consent screen_, configure o ecrã de consentimento (tipo Externo numa loja pública, e acrescente o seu domínio aos domínios autorizados).
3. Em _Credentials → Create credentials → OAuth client ID_, escolha _Web application_.
4. Em _Authorized redirect URIs_, cole o URI apresentado no cartão Google do Social Connect (forma: `https://o-seu-dominio.com/?dfsc_action=callback&dfsc_provider=google`).
5. Para ativar o Google One-Tap, acrescente também o seu domínio raiz em _Authorized JavaScript origins_.
6. Copie o _Client ID_ e o _Client secret_ para os campos correspondentes do cartão Google, ative o interruptor do fornecedor, e assinale _Mostrar o convite One-Tap aos visitantes sem sessão_, se quiser.

O One-Tap funciona com verificação completa da assinatura JWKS e controlo das claims `aud`, `iss` e `exp`. A validação é criptográfica, não apenas declarativa.

### Apple (Sign in with Apple)

1. No [Apple Developer](https://developer.apple.com/) (exige conta paga), vá a _Certificates, Identifiers & Profiles → Identifiers_.
2. Crie um _App ID_ com a capability _Sign In with Apple_ ativa.
3. Crie depois um _Services ID_ (é este identificador que vai usar como «Client ID» do lado do Social Connect). Configure o seu Sign In with Apple: acrescente o seu domínio em _Domains_, e o URI de redirecionamento apresentado no cartão Apple em _Return URLs_.
4. Crie uma chave privada (_Keys → +_), com _Sign In with Apple_ assinalado, associada ao seu App ID. Descarregue o ficheiro `.p8` (só pode descarregá-lo uma vez).
5. No cartão Apple, indique o _Services ID_, o seu _Team ID_ (visível no canto superior direito do portal), o _Key ID_ (apresentado ao lado da chave criada), e cole o conteúdo completo do ficheiro `.p8` na área _Chave privada_ (incluindo as linhas `-----BEGIN PRIVATE KEY-----`).

A Apple só devolve o nome do utilizador no primeiro consentimento, e nunca fornece fotografia de perfil. Se o utilizador ativar o «Hide My Email», é fornecido um e-mail de retransmissão da Apple, que o plugin usa normalmente. Se recusar partilhar o endereço, o plugin gera automaticamente um e-mail técnico.

### Facebook

1. No [Meta for Developers](https://developers.facebook.com/), crie uma aplicação do tipo _Consumer_.
2. Na aplicação, acrescente o produto _Facebook Login → Web_.
3. Nas definições do Facebook Login, acrescente o URI de redirecionamento apresentado no cartão Facebook em _Valid OAuth Redirect URIs_.
4. Obtenha o _App ID_ e o _App Secret_ em _Settings → Basic_ e cole-os no cartão Facebook.

O plugin reforça cada chamada à Graph API com o `appsecret_proof` (HMAC-SHA256 do token assinado com o seu App Secret), em conformidade com as boas práticas da Meta.

### Microsoft

1. No [Microsoft Entra (antigo Azure AD)](https://entra.microsoft.com/), vá a _App registrations → New registration_.
2. Dê um nome à sua aplicação. Em _Supported account types_, escolha _Accounts in any organizational directory and personal Microsoft accounts_ se quiser aceitar ambos (usa o tenant `common`).
3. Em _Redirect URI_, escolha _Web_ e cole o URI apresentado no cartão Microsoft.
4. Depois de criada, copie o _Application (client) ID_ para o campo correspondente.
5. Em _Certificates & secrets_, crie um _New client secret_ e copie de imediato o valor (deixa de ser visível depois) para o campo _Client Secret_.
6. Deixe o campo _Tenant_ em `common` para aceitar contas profissionais e pessoais, ou indique o ID do seu tenant para restringir a uma organização.

### LinkedIn

1. No [LinkedIn Developers](https://www.linkedin.com/developers/), crie uma aplicação ligada à sua página de empresa.
2. No separador _Products_, peça a ativação de _Sign In with LinkedIn using OpenID Connect_. A aprovação é automática.
3. No separador _Auth_, acrescente o URI de redirecionamento apresentado no cartão LinkedIn em _Authorized redirect URLs_.
4. Obtenha o _Client ID_ e o _Client Secret_ no separador _Auth_ e cole-os no Social Connect.

### X (Twitter)

1. No [portal de programadores do X](https://developer.x.com/), crie um projeto e depois uma aplicação.
2. Em _User authentication settings_, ative o OAuth 2.0, escolha o tipo _Confidential client_ (recomendado), e cole o URI de redirecionamento apresentado no cartão X em _Callback URI / Redirect URL_.
3. Indique o seu _Website URL_ (página inicial da sua loja).
4. Obtenha o _Client ID_ e o _Client Secret_ e cole-os no Social Connect.

A API v2 do X não devolve o endereço de e-mail. O plugin gera automaticamente um endereço técnico para criar a conta WordPress correspondente. Se fizer questão de um e-mail real, o utilizador pode sempre atualizá-lo na sua área de cliente.

## Posicionamento e aparência

No separador _Aparência_, escolhe onde apresentar os botões:

- **Formulário de início de sessão** do WooCommerce (página A minha conta sem sessão).
- **Formulário de registo** do WooCommerce.
- **Página de checkout**, por cima do formulário.
- **Painel de A minha conta**, com a lista das contas ligadas e os botões de associação manual.

Também pode inserir os botões em qualquer sítio através do shortcode:

```
[datafirefly_social_connect]
[datafirefly_social_connect context="login" heading="yes" providers="google,apple"]
[datafirefly_social_connect context="custom" redirect="https://o-seu-site/destino/"]
```

A aparência é parametrizável em quatro eixos:

- **Estilo**: cheio (cores da marca), contorno (fundo branco, contorno colorido), mínimo (fundo cinzento-claro).
- **Forma**: arredondado, pílula, quadrado.
- **Disposição**: empilhados ou em linha.
- **Texto**: «Continuar com…», «Iniciar sessão com…» ou apenas o ícone.

## Painel estatístico

O painel (menu _Social Connect → Estatísticas_) reúne toda a atividade de início de sessão social da sua loja.

### KPI e gráficos

Seletor de período no canto superior direito: 7, 30, 90 ou 365 dias. Os seis KPI apresentados cobrem:

- **Inícios de sessão**: total de autenticações no período.
- **Registos**: novas contas criadas através do início de sessão social.
- **Contas ligadas (total)**: número acumulado de identidades sociais associadas a utilizadores.
- **Encomendas atribuídas** e **volume de negócios atribuído**: ver a secção seguinte.
- **Taxa de conversão**: rácio entre encomendas e inícios de sessão.

Quatro gráficos completam os KPI: uma curva de evolução no tempo por fornecedor, um donut de repartição por fornecedor, um donut de repartição por tipo de dispositivo (computador, telemóvel, tablet) e um cartão «Top de países» alimentado pela geolocalização.

### Atribuição das encomendas

Cada encomenda WooCommerce feita por um utilizador que chegou através do início de sessão social é atribuída ao seu fornecedor de origem. A atribuição assenta na meta de utilizador `_dfsc_registered_via` e, como recurso, na primeira ligação social ativa do utilizador.

São escutados os hooks `woocommerce_checkout_order_processed` e `woocommerce_store_api_checkout_order_processed`, o que cobre tanto o checkout clássico como o checkout em blocos.

## Teste A/B dos botões

No separador _Aparência_, ative o bloco _Teste A/B dos botões_ e configure a variante B (estilo, forma, disposição, texto). A partir desse momento, cada visitante recebe aleatoriamente a variante A (as suas definições base) ou a variante B (cookie `dfsc_ab`, 50/50, conservado 30 dias).

Uma impressão é contada uma vez por sessão de visitante (cookie `dfsc_ab_imp`), para não inflacionar o volume. As conversões são medidas nos eventos de início de sessão, registo, ligação e encomenda, e apresentadas no cartão _Teste A/B_ do painel, com impressões, conversões, encomendas atribuídas, taxas por variante e designação automática da variante vencedora.

Para obter um resultado estatisticamente significativo, conte com pelo menos 500 impressões por variante. Abaixo de 200, os desvios medidos são essencialmente ruído.

## Antifraude: velocidade de início de sessão

No separador _Privacidade_, pode ativar a limitação de velocidade por endereço IP. Três limiares são configuráveis:

- **Tentativas máximas**: 8 por predefinição.
- **Janela (minutos)**: 5 por predefinição.
- **Duração do bloqueio (minutos)**: 15 por predefinição.

Depois de ultrapassado o limite, o IP fica bloqueado durante o tempo configurado. É registado um evento do tipo `blocked`, que aparece na atividade recente. A proteção aplica-se tanto aos redirecionamentos OAuth clássicos como ao fluxo Google One-Tap.

Independentemente disso, o plugin mantém uma lista de domínios de e-mail descartáveis (Mailinator, Yopmail, 10MinuteMail, etc.) que podem ser bloqueados no registo. A lista é extensível através do filtro `dfsc_disposable_domains`.

## Geolocalização

Ative a geolocalização no separador _Privacidade_. O plugin usa a base MaxMind **já incluída no WooCommerce**: não é feita qualquer chamada a um serviço externo. Se ainda não tiver ativado a geolocalização do lado do WooCommerce, vá a _WooCommerce → Definições → Geral_ e ative a opção de geolocalização por predefinição (o WooCommerce descarrega automaticamente a base de dados).

Depois de ativada, o país de cada início de sessão é resolvido e alimenta o cartão _Top de países_ do painel e a coluna «País» da exportação CSV.

## Exportação CSV

O botão _Exportar em CSV_ no topo do painel exporta todos os eventos do período selecionado. O ficheiro inclui uma coluna para cada campo pertinente (data em UTC, evento, fornecedor, contexto, país, dispositivo, variante A/B, utilizador, encomenda, montante, mensagem). É acrescentado o BOM UTF-8 no início do ficheiro para que o Excel e o LibreOffice Calc apresentem corretamente os acentos.

## Ligação de contas

Coexistem três mecanismos para ligar uma identidade social a uma conta WordPress:

1. **Identidade já conhecida**: o utilizador já usou esse fornecedor, e o início de sessão é imediato.
2. **Ligação automática por e-mail**: já existe um utilizador WordPress com o mesmo endereço de e-mail que o devolvido pelo fornecedor. Se o e-mail estiver verificado pelo fornecedor (e a opção _E-mail verificado exigido_ estiver ativa), a ligação é feita automaticamente.
3. **Ligação manual**: a partir do painel de _A minha conta_, um cliente com sessão iniciada pode associar ou dissociar cada fornecedor através do painel _Contas ligadas_.

## RGPD e privacidade

Estão disponíveis três modos de armazenamento dos IP no separador _Privacidade_:

- **Com hash** (por predefinição): HMAC-SHA256 com o `wp_salt`, não reversível.
- **Completo**: IP em claro (a usar apenas se a sua política de privacidade o mencionar explicitamente).
- **Nenhum**: o IP não é registado de todo.

O plugin declara um _exporter_ e um _eraser_ junto do sistema RGPD nativo do WordPress (_Ferramentas → Exportar / Apagar dados pessoais_). Na eliminação de um utilizador, as suas contas ligadas e os seus eventos são também eliminados (ou anonimizados em caso de apagamento).

## Shortcode e integração avançada

O shortcode `[datafirefly_social_connect]` aceita os seguintes atributos:

- `context`: `login`, `register`, `checkout` ou `custom`.
- `heading`: `yes` ou `no`, para apresentar o título «Início de sessão rápido» por cima dos botões.
- `providers`: lista separada por vírgulas para limitar a apresentação (por exemplo `google,apple`).
- `redirect`: URL absoluto de redirecionamento após o início de sessão (prevalece sobre a definição global).

Também pode chamar a apresentação diretamente em PHP:

```
echo do_shortcode('[datafirefly_social_connect context="custom" providers="google,microsoft"]');
```

## Hooks e filtros para programadores

- `dfsc_disposable_domains` (filtro): estende ou substitui a lista de domínios de e-mail descartáveis.
- `dfsc_user_registered` (ação): acionada logo após a criação de uma conta através do início de sessão social, com o ID do utilizador e o perfil normalizado.
- `dfsc_after_login` (ação): acionada após cada início de sessão bem-sucedido.
- `dfsc_welcome_subject` e `dfsc_welcome_body` (filtros): personalizam o assunto e o corpo do e-mail de boas-vindas.
- `dfsc_placeholder_email_domain` (filtro): altera o domínio usado nos e-mails técnicos (Apple Hide My Email recusado, X).

Uma API REST apenas de leitura expõe as estatísticas agregadas em `/wp-json/datafirefly-social-connect/v1/stats?days=30` (exige a permissão `manage_woocommerce`). Ative-a no separador _Privacidade_.

## Compatibilidade

- **WooCommerce HPOS**: a compatibilidade `custom_order_tables` é declarada na ativação, e as suas encomendas em armazenamento de alto desempenho são suportadas sem reservas.
- **Blocos de checkout**: o hook `woocommerce_store_api_checkout_order_processed` é escutado em paralelo com o hook clássico, e a atribuição das encomendas funciona nos dois tipos de checkout.
- **Polylang e WPML**: as cadeias de interface são traduzíveis através do ficheiro `.pot` fornecido (FR, EN, ES, DE, IT). O conteúdo (e-mail de boas-vindas, etc.) é compatível com os dois plugins multilingues.
- **Multisite**: cada site da rede tem as suas próprias tabelas e opções. A desinstalação limpa cada site.

## Desinstalação

Na remoção do plugin a partir de _Plugins_, o ficheiro `uninstall.php` é executado automaticamente. Elimina:

- As tabelas `wp_dfsc_connections` e `wp_dfsc_events`.
- As opções `dfsc_settings` e `dfsc_db_version`.
- Os transientes associados (cache JWKS da Google, cache do client secret da Apple, tokens de estado).
- Os metadados de utilizador (`_dfsc_provider`, `_dfsc_registered_via`, `_dfsc_avatar_id`, etc.).

Os seus utilizadores WordPress e as suas encomendas WooCommerce nunca são tocados. Em multisite, a desinstalação percorre todos os sites da rede.

## FAQ e resolução de problemas

### O botão Google mostra-me «redirect_uri_mismatch»

O URI de redirecionamento colado na Google Cloud Console não corresponde exatamente ao apresentado no cartão Google do Social Connect. Verifique que copiou mesmo o URI completo (com `https://`, a barra final e os parâmetros `?dfsc_action=callback&dfsc_provider=google`).

### A Apple devolve-me «invalid_client»

Três causas possíveis: o _Services ID_ indicado não é um Services ID mas um App ID, o _Team ID_ está errado, ou o conteúdo da chave privada `.p8` está incompleto (linhas `-----BEGIN PRIVATE KEY-----` em falta). Volte a verificar os três e limpe a cache do client secret da Apple guardando de novo as definições.

### O Facebook devolve-me um erro de `appsecret_proof`

O App Secret introduzido está incorreto ou foi regerado do lado da Meta sem ter sido atualizado aqui. Vá ao Meta for Developers, copie de novo o segredo e cole-o no cartão Facebook.

### O X / Twitter devolve-me «invalid_request» no momento do retorno

O _Callback URI_ não foi corretamente preenchido no portal de programadores do X, ou o tipo de aplicação não é _Confidential client_ quando o Client Secret é obrigatório. Volte a verificar o portal.

### O painel está vazio apesar de ter havido inícios de sessão

Verifique que o período selecionado cobre mesmo os inícios de sessão (30 dias por predefinição). Se acabou de ativar o plugin, espere ter pelo menos alguns eventos para ver os gráficos ganharem vida.

### O teste A/B mostra taxas a 0%

É preciso um mínimo de impressões e de conversões para que as taxas se tornem significativas. Conte com algumas centenas de impressões por variante antes de interpretar os resultados.

### A geolocalização não devolve nenhum país

Verifique que o WooCommerce descarregou mesmo a base MaxMind. Vá a _WooCommerce → Definições → Geral_, ative a geolocalização por predefinição e aguarde alguns minutos. A base é depois atualizada automaticamente pelo WooCommerce.

### Como forçar a dissociação de uma conta do lado da administração?

Vá à tabela `wp_dfsc_connections` e elimine a linha correspondente. No próximo início de sessão através desse fornecedor, o utilizador é tratado como uma identidade nova (associada à sua conta WordPress por e-mail, se a ligação automática estiver ativa).