Login com Google, Apple e Facebook para PrestaShop: documentação DataFirefly Social Connect

Apresentação

O DataFirefly Social Connect acrescenta ao PrestaShop 8 e 9 o login e o registo com um clique através do Google, da Apple e do Facebook. Os botões aparecem na página de login, na página de registo e, como opção, no checkout. O cliente gere as contas associadas numa página «Contas ligadas» da sua área de cliente.

O módulo inclui também um painel de estatísticas (conversão por serviço, dispositivos, horas de login, receita), um vale de boas-vindas opcional e um webhook assinado para o seu CRM.

Esta documentação corresponde à versão 1.1.0. É compatível com PrestaShop 8.0.0 a 9.x e PHP 7.4 a 8.3, com cURL e OpenSSL. Não é necessária nenhuma dependência Composer.

Instalação

1. Transfira o arquivo do módulo a partir da sua conta de cliente em datafirefly.com.
2. No back-office, abra Módulos > Gestor de módulos > Carregar um módulo e envie o ZIP.
3. Clique em Instalar. O módulo cria 5 tabelas (ps_dfsc_identity, ps_dfsc_log, ps_dfsc_stats_daily, ps_dfsc_button_click, ps_dfsc_consent) e guarda as definições predefinidas.
4. Clique em Configurar. Enquanto nenhum serviço estiver ativo, o módulo abre diretamente o separador Serviços e os botões ficam ocultos na loja.

Atualização a partir da versão 1.0.0

Envie o novo ZIP no gestor de módulos: a atualização é executada automaticamente. As credenciais, as definições, as associações dos clientes e as estatísticas são mantidas. A atualização ajusta os índices da tabela de associações, regista os novos hooks, acrescenta as novas definições e remove o separador de administração oculto da 1.0.0, que deixou de ser necessário.

Depois da atualização, abra o separador Serviços e compare os URIs de retorno mostrados com os registados no Google, na Apple e no Facebook. Passam a ser sempre criados no idioma predefinido da loja. Numa loja multilingue cujo back-office estava noutro idioma, o URI pode ter mudado.

Configuração dos serviços

Cada serviço pede credenciais criadas na respetiva consola de programador. O separador Serviços mostra o URI de retorno exato a copiar para cada consola: a mais pequena diferença provoca um erro redirect_uri_mismatch.

Estes URIs são criados no idioma predefinido da loja e não mudam consoante o idioma do visitante: basta um URI por serviço. O cliente regressa depois no seu idioma.

Um serviço só aparece na loja se estiver ativado e se todas as credenciais estiverem preenchidas. A faixa do separador indica para cada um se está ativo, incompleto ou desativado.

Os campos secretos (Segredo do cliente, Segredo da app, chave privada da Apple) nunca voltam a ser mostrados depois de guardados. Deixe-os vazios para manter o valor atual.

Google

1. Abra a Google Cloud Console, secção Credenciais.
2. Crie ou selecione um projeto e depois Criar credenciais > ID do cliente OAuth, tipo Aplicação Web.
3. Em URIs de redirecionamento autorizados, cole o URI mostrado no módulo (formato: https://a-sua-loja.pt/pt/module/dfsocialconnect/callback?provider=google).
4. Cole o ID de cliente e o Segredo do cliente no módulo, ative o Google e guarde.

Apple

1. Abra Apple Developer, Identifiers (é necessária uma conta de programador Apple paga).
2. Crie um Services ID (e não um App ID). O seu identificador, por exemplo com.asualoja.signin, é o Services ID a introduzir no módulo.
3. Ative o Sign in with Apple nesse Services ID, indique o domínio mostrado pelo módulo e o URI de retorno (provider=apple) em Return URL.
4. Em Keys, crie uma chave com o Sign in with Apple ativado e transfira o ficheiro AuthKey_XXXXXXXXXX.p8. A Apple só permite transferi-lo uma vez.
5. Introduza no módulo o Services ID, o Team ID (10 caracteres, no canto superior direito da consola da Apple), o Key ID (10 caracteres) e o conteúdo completo do ficheiro .p8, incluindo as linhas BEGIN e END.
6. Ative a Apple e guarde. O módulo verifica a chave de imediato e mostra «Está guardada uma chave válida.» ou um erro.

O client_secret pedido pela Apple é um token JWT assinado em ES256 com a sua chave .p8. O módulo gera-o a cada login com uma validade de 5 minutos: não é necessária nenhuma rotação manual.

Os clientes que optam por ocultar o endereço recebem um endereço @privaterelay.appleid.com. Para que os seus emails de encomenda lhes cheguem, registe o seu domínio de envio no serviço Private Email Relay da sua conta Apple Developer.

A Apple devolve o cliente à loja através de um pedido POST vindo do seu próprio site. Os navegadores não lhe juntam o cookie do PrestaShop. O módulo deteta este caso e repete o pedido a partir da loja, o que preserva a sessão e o carrinho do cliente. Não precisa de configurar nada.

Facebook

1. Abra Meta for Developers e crie uma app.
2. Adicione o produto Facebook Login e peça a permissão email.
3. Em Facebook Login > Definições, cole o URI de retorno mostrado pelo módulo (provider=facebook) em URIs de redirecionamento OAuth válidos.
4. Copie o ID da app e o Segredo da app (Definições > Básicas) para o módulo, ative o Facebook e guarde.

O módulo usa a Facebook Graph API v23 e acrescenta appsecret_proof a cada chamada: um token de acesso roubado não pode ser reutilizado sem o segredo da sua app.

Percurso do cliente

Login e criação de conta

Quando o cliente regressa do Google, da Apple ou do Facebook, o módulo procede por esta ordem:

1. Se essa conta social já estiver associada a um cliente da loja, o cliente inicia sessão.
2. Se o email corresponder a um cliente existente e o serviço o tiver verificado e a associação automática estiver ativa, o serviço é associado a essa conta e o cliente inicia sessão.
3. Se o email corresponder a um cliente existente sem poder ser associado, não é criada nenhuma conta. O cliente vê a mensagem: «Já existe uma conta com este endereço de email. Inicie sessão com a sua palavra-passe e depois associe este serviço em “Contas ligadas” na sua conta.»
4. Caso contrário, é criada uma conta com o nome próprio, o apelido e o email transmitidos, no idioma em que o cliente estava a navegar, com uma palavra-passe aleatória encriptada.

As contas desativadas não conseguem iniciar sessão. Numa multiloja sem partilha de clientes, uma conta social nunca inicia a sessão de um cliente de outra loja.

No login, o módulo aciona os hooks nativos actionAuthentication e, para uma conta nova, actionCustomerAccountAdd. As regras de carrinho automáticas são recalculadas, tal como com o formulário do PrestaShop. Se a opção do PrestaShop de email de confirmação estiver ativa, o novo cliente recebe o email de boas-vindas habitual.

Regresso à página de origem

Depois do login, o cliente regressa à página de onde saiu, por exemplo o checkout. Se não houver página de origem, chega à página escolhida no separador Comportamento. Só são aceites endereços da sua loja: um link malicioso não pode enviar o cliente para outro site.

Página «Contas ligadas»

É acrescentado um bloco «Contas ligadas» à página A minha conta (temas Classic e Hummingbird). Abre uma página que lista cada serviço com o respetivo estado. Para um serviço associado, a página mostra o nome, o email, a data de associação e o avatar, se tiver sido importado.

• Associar: inicia o login no serviço e associa-o à conta do cliente.
• Desassociar: remove a associação após confirmação. Se for a última conta associada, o cliente é convidado a definir primeiro uma palavra-passe com «Esqueceu-se da palavra-passe?» para manter o acesso à conta.

Separador Comportamento

• Associação automática por email verificado: associa o serviço a uma conta existente quando o fornecedor confirmou o mesmo email. Se estiver desativada, o cliente tem de iniciar sessão com a palavra-passe e depois associar o serviço a partir da sua conta. Ativada por predefinição.
• Importar o avatar localmente: guarda a foto de perfil em /img/dfsc/avatars/ (só HTTPS, 2 MB no máximo, JPEG, PNG, GIF ou WebP verificados) e mostra-a na página Contas ligadas.
• Subscrever as novas contas na newsletter: o RGPD exige um consentimento explícito. Ative esta opção apenas se recolher esse consentimento de outra forma.
• Aviso legal por baixo dos botões: escolha uma página CMS (os seus termos e condições ou a sua política de privacidade). A frase «Ao continuar, aceita os nossos [página]» aparece por baixo dos botões e a aceitação é registada para cada conta criada. Escolha «Nenhum» para ocultar o aviso.
• Vale de boas-vindas: cria, para cada conta criada através de um serviço, um vale de utilização única, válido 90 dias e mostrado no carrinho do cliente. Defina o prefixo do código (letras, algarismos, hífenes, 40 caracteres no máximo) e o montante com IVA na moeda predefinida. O código tem o formato WELCOME-GOOGLE-A1B2C3. O cliente é informado logo após o login.
• Grupos de clientes por serviço: acrescenta os novos clientes ao grupo escolhido consoante o serviço utilizado.
• Tentativas máx. por endereço IP: número de logins iniciados a partir do mesmo IP em 15 minutos. Por predefinição 20, de 1 a 500.
• Página após o login: A minha conta, página inicial, checkout, histórico de encomendas ou dados pessoais. Usada quando o cliente não vem de uma página específica.
• Guardar registos e cliques: de 30 a 3 650 dias, 365 por predefinição. Os registos contêm endereços IP e são eliminados automaticamente uma vez por dia. As estatísticas diárias do painel são mantidas.
• Webhook de saída: URL e segredo, ver mais abaixo.

Separador Aparência

• Estilo dos botões: rounded (predefinido), pill, square, ghost ou minimal. Em ecrãs grandes, os botões aparecem lado a lado e passam para a linha seguinte em vez de cortar o texto.
• Texto dos botões: «Continuar com», «Iniciar sessão com» ou «Registar-se com». A página de registo usa sempre «Registar-se com».
• Mostrar também os botões no checkout: passo «Dados pessoais», para visitantes sem sessão iniciada. Ativado por predefinição.

Os botões são sempre mostrados nas páginas de login e de registo, desde que pelo menos um serviço esteja ativo.

Painel

O primeiro separador da configuração apresenta as estatísticas de 7, 30, 90 ou 365 dias. Em multiloja, acompanha a loja ou o grupo selecionado no back-office.

• Indicadores: logins bem-sucedidos, cliques nos botões com a taxa de conversão, novos clientes, falhas.
• Logins ao longo do tempo, dia a dia e por serviço.
• Repartição por serviço e taxa de conversão por serviço: uma taxa anormalmente baixa indica muitas vezes um serviço mal configurado.
• Dispositivos e principais navegadores.
• Mapa dia × hora dos logins bem-sucedidos (hora do servidor).
• Taxa de adoção: parte das contas de cliente ativas associadas a cada serviço.
• Receita dos clientes com login social: encomendas válidas do período, com IVA, na moeda de cada encomenda. Cada cliente conta uma só vez, no primeiro serviço associado.
• Atividade recente: os 25 eventos mais recentes (criações, logins, associações, desassociações, falhas) com o erro exato devolvido pelo fornecedor.

Webhook CRM

O módulo pode enviar um POST JSON para o URL à sua escolha nos eventos identity.login (login ou criação de conta), identity.linked (associação a partir de Contas ligadas) e identity.unlinked (desassociação). A chamada está limitada a 3 segundos para não atrasar o cliente. Em caso de falha, o erro é registado nos registos do PrestaShop.

O corpo é assinado com HMAC-SHA256 usando o segredo do webhook. É gerado um segredo aleatório na instalação. A assinatura é enviada no cabeçalho X-Dfsc-Signature no formato sha256=<hex> e o nome do evento em X-Dfsc-Event. Do lado da receção, recalcule o HMAC sobre o corpo em bruto e compare.

{
  "event": "identity.login",
  "sent_at": "2026-10-14T11:27:45+02:00",
  "data": {
    "id_customer": 1234,
    "provider": "google",
    "event": "created",
    "email": "marie.dupont@example.com",
    "id_shop": 1
  }
}

O campo data.event vale created (conta criada), linked (associada a uma conta existente por email verificado) ou login (login de um cliente já associado).

RGPD

• O aviso legal por baixo dos botões informa o cliente antes da criação da conta. A aceitação é registada em ps_dfsc_consent, juntamente com o estado da subscrição da newsletter.
• Os registos e os cliques, que contêm endereços IP, são eliminados segundo o prazo escolhido.
• O cliente pode desassociar cada serviço na página Contas ligadas.
• Com o módulo oficial psgdpr, a exportação dos dados do cliente inclui as contas associadas, e a eliminação dos seus dados apaga as associações, os consentimentos e os avatares.
• Quando um cliente é eliminado no back-office, as associações, os consentimentos e os avatares são eliminados e as linhas de registo são anonimizadas.

Idiomas

O módulo é fornecido em inglês, francês, espanhol, alemão, italiano, neerlandês, polaco e português, tanto na loja como no back-office. Os textos podem ser alterados em Internacional > Traduções > Traduções de módulos instalados.

Desinstalação

A partir do gestor de módulos, a desinstalação elimina as 5 tabelas ps_dfsc_*, todas as chaves de configuração DFSC_* e a pasta /img/dfsc/ dos avatares importados. As contas de cliente e as respetivas encomendas mantêm-se intactas: só as associações sociais são apagadas.

Resolução de problemas

Comece sempre pela lista Atividade recente do painel: mostra o erro exato devolvido pelo fornecedor.

redirect_uri_mismatch (Google) ou URL bloqueado (Facebook): o URI registado no fornecedor não corresponde exatamente ao mostrado pelo módulo. Verifique o https, o www, o prefixo de idioma e o parâmetro ?provider=.

invalid_client (Apple): Team ID ou Key ID errados, chave .p8 incompleta, Services ID confundido com um App ID, ou Return URL diferente do mostrado pelo módulo. Se o módulo indicar que a chave guardada não pode ser lida, cole-a novamente.

invalid_grant: o código de autorização expirou ou já foi utilizado, por exemplo depois de o cliente voltar atrás no navegador. Basta iniciar o login de novo.

«A sua sessão de login expirou»: passaram mais de 15 minutos no ecrã do fornecedor, ou o cookie da loja foi bloqueado. Inicie o login de novo.

«Já existe uma conta com este endereço de email»: o fornecedor não confirmou o email, ou a associação automática está desativada. O cliente inicia sessão com a palavra-passe e depois associa o serviço em Contas ligadas.

«Demasiadas tentativas»: foi atingido o limite por IP. Aguarde 15 minutos ou aumente o limite em Comportamento, por exemplo numa empresa em que todos os postos partilham o mesmo IP.

Um botão não aparece: verifique na faixa da configuração que o serviço está «ativo» e não «incompleto». Depois, limpe a cache do PrestaShop.

O vale de boas-vindas não é criado: verifique se a opção está ativada e se o montante é superior a zero. O vale só é criado para uma conta nova, e não quando o serviço é associado a uma conta existente.