DataFirefly Social Connect: guia completo

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

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

Apple (Sign in with Apple)

1. No Apple Developer (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-----).

Facebook

1. No Meta for Developers, 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), 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, 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, 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.

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.

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