Checkout Simples e Elegante (dfsimplecheckout): guia completo

Apresentação

O DataFirefly Simple Checkout substitui o checkout nativo de 5 etapas do PrestaShop por um processo de compra numa só página, moderno e inspirado nos checkouts da Shopify e da Stripe. O módulo monta o seu controlador em tempo de execução através do hook actionDispatcher: não é escrito qualquer ficheiro de override em disco e os overrides de terceiros que já tenha no OrderController são herdados corretamente.

Funcionalidades principais: disposição em duas colunas com resumo permanente, início de sessão social com Google e Facebook, preenchimento automático de morada com o Google Places, formulário de morada adaptável ao país, código promocional por AJAX, três cores personalizáveis e modo sem distrações.

Instalação

1. No seu back-office PrestaShop, vá a Módulos → Gestor de módulos → Instalar um módulo.
2. Selecione o ficheiro dfsimplecheckout.zip descarregado a partir da sua conta DataFirefly.
3. Clique em Instalar e depois em Configurar.
4. Limpe a cache do PrestaShop (Parâmetros avançados → Desempenho → Limpar a cache).
5. Visite a página /order da sua loja com um produto no carrinho: o novo checkout aparece de imediato.

Configuração geral

Cores

Podem configurar-se três cores no separador de definições do módulo:

• Cor principal — botões, ligações, estados ativos e opções selecionadas (predefinição #1a73e8).
• Cor dos botões ao passar o rato — estado de passagem nos botões principais «Continuar» e «Encomendar» (predefinição #1559b8).
• Cor de destaque / sucesso — indicadores de etapa concluída, pastilha de código promocional aplicado, etiqueta «Grátis» da transportadora e mensagens de sucesso (predefinição #008060).

Os três valores são injetados como variáveis CSS (--dfsc-primary, --dfsc-primary-hover, --dfsc-success) e validados por uma expressão regular hexadecimal estrita.

Logótipo

Indique o URL de um logótipo personalizado para o cabeçalho do checkout; na sua falta, é usado o logótipo da loja. Dimensões renderizadas: 190×42 px no máximo.

Modo sem distrações

A opção Ocultar o cabeçalho e o rodapé do tema (ativada por predefinição) elimina o cabeçalho completo do tema (menu, pesquisa, carrinho) e o seu rodapé, apenas na página /order. A implementação sobrepõe os blocos Smarty header e footer no nosso template: num tema que não utilize estes blocos padrão, a opção fica simplesmente sem efeito, nunca resultando numa página em branco.

Outras opções

• Campo de nota para o vendedor (ativado/desativado)
• Campo de código promocional (ativado/desativado)
• Selos de confiança — HTML livre apresentado por baixo do resumo
• Ligações legais no fundo do checkout (condições de venda, privacidade, devoluções, detetadas através dos papéis nativos das páginas CMS)

Início de sessão social com Google

Criar as credenciais

1. Vá à Google Cloud Console e crie (ou selecione) um projeto.
2. Em APIs & Services → Credentials, crie um OAuth client ID do tipo Web application.
3. Em Authorized JavaScript origins, acrescente o URL da sua loja (por exemplo, https://www.aminhaloja.pt), sem caminho e com o protocolo https.
4. Copie o Client ID gerado (termina em .apps.googleusercontent.com).

Configurar o módulo

1. Nas definições do módulo, ative o Google Sign-In e cole o Client ID.
2. Grave e limpe a cache.
3. Em /order, o botão da Google aparece por cima dos separadores «Sou um novo cliente / Já tenho conta».

O fluxo: o cliente clica, seleciona a sua conta Google e o módulo recebe um token JWT que valida do lado do servidor através do endpoint oficial tokeninfo (verificação da audiência, do emissor, da expiração e do e-mail verificado). Se já existir uma conta de cliente com esse e-mail, a sessão é iniciada; caso contrário, é criada automaticamente uma conta com o nome próprio e o apelido do perfil Google.

Início de sessão social com Facebook

Criar a aplicação

1. No Meta for Developers, crie uma aplicação do tipo Consumer.
2. Acrescente o produto Facebook Login e declare o seu domínio nas definições.
3. Obtenha o App ID e o App Secret em Settings → Basic.

Configurar o módulo

Ative o Facebook Login nas definições, cole o App ID e o App Secret e grave. A validação no servidor é feita em duas etapas: debug_token (verifica que o token pertence mesmo à sua aplicação) e depois a obtenção do perfil com assinatura appsecret_proof (HMAC-SHA256). O App Secret nunca sai do seu servidor.

Preenchimento automático de morada com o Google Places

1. Na Google Cloud Console, ative as APIs Places API e Maps JavaScript API.
2. Crie uma chave de API e restrinja-a ao seu domínio (recomendado).
3. No módulo, ative o Preenchimento automático de morada e cole a chave.

O campo «Morada» do formulário passa então a propor sugestões durante a escrita. A seleção de uma sugestão preenche previamente a rua, o complemento, a localidade, o código postal, o país e, quando aplicável, a região. As sugestões estão limitadas aos países ativos da sua loja (até 5 países, limite da API da Google).

Formulário de morada adaptável ao país

O formulário de morada adapta-se automaticamente ao país selecionado:

• O país predefinido da lista pendente é o configurado em Internacional → Localização do seu back-office (e não o primeiro país por ordem alfabética).
• O campo Estado/Região só aparece nos países que os têm (EUA, Espanha, Itália…) e a sua lista apresenta apenas as regiões ativas do país selecionado.
• O campo DNI aparece nos países que o exigem (Espanha).
• A validação do código postal utiliza o formato do país.
• Ao mudar de país, a página é recarregada com o formulário reestruturado para o novo país.

Edição de moradas

Cada morada guardada apresenta um ícone de lápis. O clique abre o formulário inline pré-preenchido com todos os valores da morada (carregados do lado do servidor, com verificação de propriedade: um cliente nunca pode consultar a morada de outro). A gravação atualiza a morada existente, sem criar duplicados.

Código promocional

O campo de código promocional (ativável) funciona por AJAX: aplicação e remoção sem recarregamento e atualização instantânea do resumo. As operações são delegadas ao controlador nativo CartController do PrestaShop, pelo que todas as regras de carrinho (datas, montante mínimo, restrições de transportadora, acumulação) são respeitadas de forma idêntica. As mensagens de erro nativas («Este código expirou», «Montante mínimo não atingido»…) são apresentadas tal como são.

Compatibilidade com transportadoras

O conteúdo adicional das transportadoras (mapa de pontos de recolha, widgets de operadores…) é renderizado através de {$carrier.extraContent}, tal como no template nativo. No caso dos pontos de recolha da Colissimo, o módulo injeta automaticamente as informações do ponto selecionado (identificador, telemóvel) nos pedidos de validação, o que elimina a falsa mensagem «Selecione um ponto de recolha» que o módulo da Colissimo podia apresentar nos checkouts de página única.

Hooks para programadores

• displayDfsimplecheckoutExpress — espaço no topo do checkout para os pagamentos expresso (Apple Pay, Google Pay, PayPal Express).
• displayDfsimplecheckoutSidebarTop / displayDfsimplecheckoutSidebarBottom — zonas de injeção na coluna do resumo.
• actionDfscSocialLogin — despoletado depois de um início de sessão social bem-sucedido, com os parâmetros customer e dfsc_social_provider (google ou facebook). Útil para marcação em CRM.

Resolução de problemas

O botão da Google não aparece

• Verifique se o Client ID está mesmo preenchido e se a opção está ativada.
• Verifique na consola do navegador se não há um erro «origin not allowed»: nesse caso, acrescente o URL exato da sua loja (com https e sem barra final) nos Authorized JavaScript origins da Google Cloud Console.

O início de sessão social não persiste

Limpe a cache do PrestaShop e a cache do navegador. Se o problema persistir, verifique se não há algum módulo de segurança de terceiros a invalidar os cookies de sessão depois do início de sessão.

O campo Estado apresenta as regiões erradas

Certifique-se de que está a utilizar a versão 1.2.20 ou superior do módulo, que resolve a estrutura do formulário do lado do servidor para cada país.

Página em branco em /order

Ative o modo de depuração do PrestaShop (_PS_MODE_DEV_) para ver o erro, ou consulte var/logs. Verifique se não há outro módulo de checkout de página única ativo em simultâneo.

Desinstalação

Desinstale o módulo a partir do Gestor de módulos. O ambiente de execução é libertado de imediato e o checkout nativo de 5 etapas é reposto. Sem ficheiros residuais e sem dados órfãos.