DataFirefly Waitlist: documentação

Apresentação

O DataFirefly Waitlist acrescenta um alerta de reposição de stock à sua loja PrestaShop 8 ou 9. Assim que um produto, ou uma combinação precisa, passa abaixo do limiar de stock configurado, um botão «Avisar-me quando voltar ao stock» aparece automaticamente na página de produto. O visitante deixa o seu e-mail e recebe um alerta assim que há reposição. Cada encomenda feita depois por um inscrito notificado é atribuída como conversão no painel.

Instalação

1. No back-office, aceda a Módulos → Gestor de módulos → Instalar um módulo.
2. Carregue o ficheiro dfwaitlist-x.x.x.zip.
3. Clique em Instalar. O módulo cria a tabela df_dfwaitlist_subscriber, regista os seus hooks e adiciona o seu separador de administração.
4. Abra a configuração para preencher o e-mail do comerciante e obter o URL do cron.

Configuração

Aceda a Módulos → DataFirefly Waitlist → Configurar. As definições disponíveis:

• Duplo opt-in: quando está ativo, a inscrição envia primeiro um e-mail de confirmação. Enquanto o visitante não clicar, a inscrição permanece não confirmada e não acionará nenhum alerta. Desativável se preferir a inscrição instantânea.
• Limiar de stock: quantidade abaixo da qual um produto é considerado indisponível e faz aparecer o botão.
• Limiar de alerta ao comerciante: número de inscritos num mesmo produto a partir do qual recebe um e-mail de notificação. 10 por defeito.
• E-mail do comerciante: destinatário do alerta acima.
• Duração de vida das inscrições: as inscrições nunca notificadas são limpas automaticamente ao fim de N dias. 90 por defeito.
• Texto do botão: personalizável por idioma.
• Menção RGPD: texto apresentado por baixo do formulário, personalizável por idioma.
• URL do cron: protegido por token, regenerável num clique a partir do back-office.

Funcionamento do lado do cliente

Aparecimento do botão

O botão é injetado através do hook displayProductActions e a sua visibilidade é decidida do lado do cliente. O módulo consulta o endpoint /modules/dfwaitlist/stockcheck para conhecer o estado de stock real da combinação apresentada, o que o torna independente do comportamento de re-renderização AJAX do tema. Resultado: o botão desaparece se a variante selecionada estiver disponível e reaparece caso contrário, sem recarregar a página.

Combinações

A inscrição é feita por par (produto, combinação). O formulário mostra explicitamente a variante em causa, por exemplo «Variante: Vermelho / Tamanho L». Quando o visitante muda de combinação antes de confirmar, o alvo muda automaticamente. O e-mail de alerta menciona a combinação exata e aponta para a página com a variante pré-selecionada: nenhuma confusão possível entre um tamanho e outro.

Confirmação (duplo opt-in)

Com o duplo opt-in ativo, o inscrito recebe um e-mail com uma ligação de confirmação com token. A inscrição só é considerada após o clique. Este mecanismo garante a qualidade da lista (nada de e-mails fantasiosos) e fornece uma prova de consentimento explícito.

Alerta de reposição de stock

Na reposição, o inscrito recebe um e-mail HTML responsivo com o nome do produto, a combinação em causa e uma ligação direta para a página. Cada e-mail contém uma ligação de cancelamento num clique.

Deteção das reposições de stock

Dois canais complementares, a manter ambos ativos:

1. Hook actionUpdateQuantity: tempo real. Assim que um colaborador modifica um stock no back-office, ou que uma encomenda anulada liberta stock, os e-mails partem imediatamente.
2. Cron de segurança: protegido por token. Apanha os movimentos de stock que não passam pelos hooks: importações API, sincronização ERP, scripts CLI, atualizações através do Webservice do PrestaShop.

Configuração do cron

Copie o URL apresentado na configuração do módulo (contém o token de segurança) e ligue-o a uma chamada horária:

0 * * * * curl -s "https://a-sua-loja.pt/module/dfwaitlist/cron?token=O_SEU_TOKEN" > /dev/null 2>&1

Seguimento de conversões

No hook actionValidateOrder, o módulo compara cada linha da encomenda com as inscrições no estado «notificado». A correspondência é feita sobre o trio (email, id_product, id_product_attribute). Em caso de correspondência, a inscrição é marcada como convertida e o id_order é registado.

Como o seguimento se baseia no e-mail e não na conta de cliente, funciona tanto para as encomendas de convidado como para os clientes com sessão iniciada.

Painel de administração

• 6 KPI: inscritos, à espera de confirmação, notificados, compras, taxa de conversão, cancelados.
• Lista dos produtos com pedidos: ordenável e paginada. É a sua lista de prioridades de reposição: um produto com 47 inscritos são 47 vendas quase garantidas se repuser rapidamente.
• Vista detalhada por produto: cada inscrito com o seu estado individual.
• Exportação CSV: exportação completa da loja ativa: e-mail, produto, combinação, estados (confirmado, notificado, comprado, cancelado), datas, IP, id da encomenda em caso de conversão. O ficheiro inclui um BOM UTF-8 para abrir diretamente no Excel sem problemas de codificação.

Alerta ao comerciante

Quando um produto esgotado atinge o limiar de inscritos configurado, um e-mail automático avisa-o com o número de pessoas à espera e uma ligação para o painel. O e-mail só é enviado uma vez por produto, para evitar o ruído. É o sinal que transforma a sua lista de espera numa ferramenta de gestão da reposição: prioriza com base em procura medida, não em intuição.

E-mails

Três modelos, cada um fornecido em FR/EN/ES/DE em formato HTML responsivo + texto simples:

• Confirmação: enviado apenas se o duplo opt-in estiver ativo, com a ligação de ativação.
• Alerta de reposição de stock: produto, combinação, ligação direta para a página, ligação de cancelamento.
• Alerta ao comerciante: número de inscritos em espera e ligação para o painel.

Os modelos são modificáveis em modules/dfwaitlist/mails/<iso>/.

RGPD e qualidade da lista

• Duplo opt-in ativável, com prova de consentimento (o IP é registado na inscrição).
• Cancelamento num clique em cada e-mail de alerta, através de um token único distinto do token de confirmação. A inscrição é marcada como cancelada sem ser eliminada, para conservar a rastreabilidade, e não parte nenhum e-mail futuro.
• Limpeza automática das inscrições nunca notificadas para além da duração configurada (90 dias por defeito): minimização dos dados.
• Honeypot anti-bot integrado no formulário, e limite de um único e-mail por produto para evitar as inscrições em rajada.
• Nenhuma chamada externa: os dados ficam na base de dados PrestaShop, delimitados por loja. Nada é enviado à DataFirefly nem a um serviço de terceiros.

Multiloja e multilingue

A tabela de inscrições tem as colunas id_shop e id_lang. Cada subloja de uma rede multiloja dispõe portanto da sua própria lista de espera, dos seus próprios alertas ao comerciante e dos seus próprios KPI. Os e-mails partem no idioma do inscrito no momento da inscrição.

Resolução de problemas

O botão não aparece

• Verifique que o produto está abaixo do limiar de stock configurado: acima, o botão é deliberadamente ocultado.
• Num produto com combinações, verifique a variante selecionada: o botão só aparece se essa variante estiver indisponível.
• O tema tem de implementar o hook displayProductActions. É o caso do Classic e do Hummingbird; num tema personalizado exótico, verifique a sua presença no template de produto.
• Esvazie a cache do PrestaShop (Parâmetros avançados → Desempenho).

Os alertas não partem na reposição

• Verifique que a inscrição está confirmada: com o duplo opt-in, uma inscrição não confirmada nunca recebe alerta.
• Se o stock foi modificado fora do back-office (API, ERP, CLI), o hook em tempo real não dispara: é o cron que assume. Verifique que está a correr e que o token do URL está atualizado.
• Teste o envio de e-mail do PrestaShop em geral (Parâmetros avançados → E-mail → Teste).

Há conversões que não são contabilizadas

A correspondência exige o e-mail e o produto e a combinação. Se o cliente encomendar com um endereço de e-mail diferente do da sua inscrição, ou comprar uma combinação diferente daquela que esperava, a conversão não é atribuída: é deliberado, para evitar falsos positivos que falseariam os seus KPI.

Desinstalação

A desinstalação elimina a tabela df_dfwaitlist_subscriber e todas as chaves de configuração com o prefixo DFWAITLIST_. Não fica nenhum rasto na base de dados. É pedida uma confirmação, uma vez que as inscrições e as estatísticas de conversão serão definitivamente perdidas: exporte o CSV antes, se quiser conservar o histórico.