DataFirefly Social Connect: documentação

Apresentação

O DataFirefly Social Connect acrescenta ao PrestaShop 8 e 9 três botões de início de sessão social (Google, Apple, Facebook) associados a um painel analítico completo. O módulo não se limita a autenticar: mede a conversão, gera automaticamente vales de boas-vindas, alimenta o seu CRM através de um webhook assinado e mantém-se 100% conforme ao RGPD.

O objetivo é duplo: eliminar a fricção da inscrição (um clique em vez de um formulário) e medir o impacto real no seu negócio (cliques, conversões, receita gerada pelos clientes sociais).

Instalação

1. Transfira o arquivo dfsocialconnect.zip a partir da sua conta de cliente em datafirefly.com.
2. No back-office do PrestaShop, aceda a Módulos > Gestor de módulos > Instalar 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 um separador de BO oculto AdminDfSocialConnect.
4. Clique em Configurar. Chega ao painel vazio: os primeiros dados aparecerão assim que um utilizador clicar num botão social.

O módulo é compatível com PrestaShop 8.0.0 a 9.99.99 e PHP 7.4 a 8.3. Não é necessária nenhuma dependência Composer externa: está incluído um autoloader PSR-4 mínimo.

Configuração dos fornecedores

Cada fornecedor exige credenciais OAuth obtidas na sua consola de programador. O módulo mostra o URL de callback exato a copiar para cada consola: é o passo mais importante, o menor erro de digitação provoca um erro redirect_uri_mismatch.

Google OAuth2 / OpenID Connect

1. Aceda a https://console.cloud.google.com/apis/credentials.
2. Crie ou selecione um projeto e clique depois em Criar credenciais > ID de cliente OAuth 2.0.
3. Tipo de aplicação: Aplicação Web.
4. Em URIs de redirecionamento autorizados, cole o URL apresentado no separador “Providers” da configuração do módulo (formato: https://a-sua-loja.pt/module/dfsocialconnect/callback?provider=google).
5. Obtenha o Client ID e o Client Secret e cole-os no módulo.
6. Ative o interruptor “Google ativo”.

Apple Sign In

1. Aceda a https://developer.apple.com/account/resources/identifiers/list (conta de programador Apple paga obrigatória).
2. Crie um Services ID (e não um App ID). Anote o seu identifier: é o seu Client ID.
3. Ative Sign In with Apple nesse Services ID, configure o domínio da sua loja e cole o URL de callback apresentado pelo módulo (provider=apple) em Return URL.
4. Em Keys, crie uma nova chave com Sign In with Apple ativo. Transfira o ficheiro .p8: nunca mais o poderá recuperar depois.
5. Obtenha o seu Team ID (no canto superior direito da consola Apple), o seu Key ID (o identificador da chave criada no passo 4) e o conteúdo integral do ficheiro .p8 (com as linhas BEGIN PRIVATE KEY e END PRIVATE KEY).
6. Cole os 4 campos na configuração do módulo (Services ID, Team ID, Key ID, conteúdo .p8).
7. Ative o interruptor “Apple ativo”.

O módulo assina o JWT client_secret em ES256 no momento e regenera-o automaticamente de 5 em 5 meses (a validade máxima autorizada pela Apple é de 6 meses). Não tem nenhuma rotação manual a gerir.

Facebook Login

1. Aceda a https://developers.facebook.com/apps.
2. Crie uma nova app de tipo Consumidores.
3. Na secção Add products, adicione Facebook Login.
4. Em Facebook Login > Settings, cole o URL de callback apresentado pelo módulo (provider=facebook) em Valid OAuth Redirect URIs.
5. Obtenha o App ID e o App Secret em Settings > Basic e cole-os no módulo.
6. Ative o interruptor “Facebook ativo”.

O módulo usa a API Graph v19.0 e ativa automaticamente o appsecret_proof, que impede o replay de um access token roubado ao exigir uma assinatura HMAC do segredo da app.

Separador Comportamento

Este separador comanda o que acontece uma vez concluído o início de sessão social.

• Auto-associação por e-mail verificado: se o e-mail devolvido pelo fornecedor estiver marcado como verificado e corresponder a uma conta de cliente existente, o módulo associa automaticamente o fornecedor a essa conta em vez de criar uma nova. Recomendado: ON.
• Importar o avatar: transfere a fotografia de perfil para /img/dfsc/avatars/<id_customer>.<ext> (limite 2 MB, lista branca MIME JPEG/PNG/WebP). Sobrevive à expiração dos CDN dos fornecedores.
• Vale de boas-vindas: para cada nova conta criada através de um início de sessão social, o módulo cria uma CartRule PrestaShop de uso único em nome do cliente. Configure o prefixo (por defeito WELCOME), o montante e a duração de validade.
• Grupo de clientes por fornecedor: atribua um ID de grupo PrestaShop a cada fornecedor (Google / Apple / Facebook). Útil para segmentar as suas campanhas de marketing por origem.
• Opt-in da newsletter por defeito: se ativo, o cliente criado é marcado como subscritor da newsletter (a ativar apenas se o seu processo incluir um duplo opt-in conforme ao RGPD).
• Limitação de pedidos: número máximo de tentativas por IP numa janela de 15 minutos. Por defeito: 30 tentativas. Acima disso, o utilizador recebe uma mensagem “Demasiadas tentativas”.
• Retenção dos registos: número de dias durante os quais conservar os registos em bruto (ps_dfsc_log e ps_dfsc_button_click). O rollup diário (ps_dfsc_stats_daily) é conservado indefinidamente e alimenta o painel.

Separador Aspeto

Escolha a apresentação visual dos botões:

• Estilo: 5 variantes: rounded (por defeito, cantos de 8 px), pill (inteiramente arredondado), square (anguloso), ghost (transparente com contorno), minimal (compacto).
• Modo de etiqueta: 3 modos: Continuar com X (por defeito, neutro), Iniciar sessão com X (página de login), Registar-se com X (página de inscrição).
• Mostrar na página de login e Mostrar na página de inscrição: interruptores independentes.
• Widget A minha conta: mostra na área de cliente uma zona “Contas ligadas” que permite associar ou desassociar cada fornecedor a qualquer momento (exigência do RGPD).

Painel analítico

O primeiro separador da configuração agrega as estatísticas de 30 dias deslizantes por defeito (configurável).

• 4 cartões KPI: Inícios de sessão bem-sucedidos, Cliques nos botões, Novos clientes criados, Falhas.
• Curva temporal: inícios de sessão bem-sucedidos por dia, segmentados por fornecedor (Google azul, Apple preto, Facebook azul Meta).
• Repartição por fornecedor: doughnut Chart.js com a percentagem de cada fornecedor.
• Taxa de conversão por fornecedor: clique vs início de sessão concluído. Permite identificar um fornecedor mal configurado (taxa anormalmente baixa).
• Repartição por dispositivo e navegador: gráfico de barras agregado na janela.
• Mapa de calor dia × hora: grelha 7 × 24 em 7 tons de azul. Identifique os picos de utilização para ajustar as suas campanhas.
• Penetração social: percentagem da sua base de clientes que tem pelo menos um fornecedor associado.
• Receita gerada pelos clientes sociais: soma das encomendas pagas dos clientes criados através de um início de sessão social, calculada por JOIN SQL em ps_orders.

Webhook CRM

A cada início de sessão bem-sucedido ou conta associada, o módulo pode enviar um pedido HTTP POST para um URL à sua escolha, em modo fire-and-forget (o tempo de resposta do seu endpoint não afeta o tempo de início de sessão do utilizador).

• URL do webhook: endpoint HTTPS recomendado. Make, n8n, Zapier ou a sua stack interna.
• Segredo partilhado: usado para assinar o payload em HMAC-SHA256. A assinatura é enviada no cabeçalho X-Dfsc-Signature. Do lado da receção, recalcule o HMAC sobre o body em bruto para validar a autenticidade.

Payload tipo enviado:

{
  "event": "social_login_success",
  "provider": "google",
  "id_customer": 1234,
  "email": "maria.silva@example.com",
  "is_new_account": true,
  "ip": "203.0.113.42",
  "timestamp": 1748378400
}

RGPD e consentimento

O módulo é concebido para respeitar o RGPD by design:

• A cada início de sessão social, é inserida uma linha em ps_dfsc_consent com carimbo temporal, IP, user agent e fornecedor: é a sua pista de auditoria.
• O widget “Contas ligadas” em A minha conta permite ao cliente desassociar um fornecedor a qualquer momento.
• A desinstalação do módulo elimina de forma limpa as 5 tabelas e todas as chaves de configuração. As contas de cliente permanecem intactas.
• Nenhum segredo OAuth é alguma vez transmitido em claro: todas as trocas passam por HTTPS e o JWT Apple é assinado localmente com a sua chave .p8.

Desinstalação

A partir de Módulos > Gestor de módulos, desinstale o módulo. O processo:

1. Elimina as 5 tabelas ps_dfsc_*.
2. Elimina o separador de BO AdminDfSocialConnect.
3. Elimina todas as chaves de configuração DFSC_*.
4. As associações sociais dos clientes são eliminadas, mas as contas de cliente e as suas encomendas permanecem intactas. Os avatares guardados em /img/dfsc/avatars/ são eliminados.

Resolução de problemas

Erro “redirect_uri_mismatch” (Google): o URL colado na consola Google não corresponde exatamente ao apresentado pelo módulo. Verifique o scheme (https), o domínio (com ou sem www) e o caminho completo. Nenhum carácter no fim (barra, espaço).

Erro “invalid_client” (Apple): o seu JWT client_secret é inválido. Causas frequentes: Team ID ou Key ID incorreto, conteúdo .p8 truncado (verifique as linhas BEGIN/END PRIVATE KEY), ou Services ID confundido com App ID.

Erro “Invalid OAuth access token signature” (Facebook): o seu App Secret está errado. Regenere-o em Settings > Basic e cole-o de novo.

“Demasiadas tentativas, por favor aguarde”: disparo do limitador de pedidos. Espere 15 minutos ou aumente o limiar em Comportamento.

As estatísticas não sobem: verifique que ps_dfsc_button_click recebe linhas (um clique em modo incógnito deve bastar). Se nada for escrito, o controlador front-office provavelmente não está acessível: verifique as suas regras de reescrita de URL.

O vale de boas-vindas não é criado: verifique que a função está ativa em Comportamento, que o montante e o prefixo estão preenchidos, e que a conta de cliente foi de facto criada (e não simplesmente associada a uma conta existente: a auto-associação não emite vale).