DataFirefly Price Alert: documentação

Apresentação

O DataFirefly Price Alert acrescenta um alerta de descida de preço à sua loja PrestaShop 8 ou 9. Os seus visitantes inscrevem-se a partir da página de produto (com ou sem conta de cliente), escolhem entre dois modos, qualquer descida ou preço alvo, e recebem um e-mail assim que o preço desce. Cada encomenda feita por um subscritor notificado é automaticamente atribuída como conversão, com a receita recuperada visível no painel de administração.

Instalação

1. No back-office, aceda a Módulos → Gestor de módulos → Instalar um módulo.
2. Carregue o ficheiro dfpricealert-x.x.x.zip.
3. Clique em Instalar. O módulo cria duas tabelas (df_pricealert_subscriber e df_pricealert_event), regista os seus hooks e adiciona o separador Price Alerts em Catálogo.

Configuração

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

• Duplo opt-in (RGPD): ativo por defeito. O subscritor recebe um e-mail de confirmação e o alerta só fica ativo após o seu clique. Fortemente recomendado para a conformidade com o RGPD.
• Modo de alerta por defeito: o modo pré-selecionado no formulário: qualquer descida ou preço alvo. O cliente pode sempre mudar.
• Posição do formulário: displayProductActions (por baixo do botão de compra) ou displayProductAdditionalInfo (zona de informações complementares).
• Percentagem mínima de descida: em modo qualquer descida, ignorar as descidas inferiores a N%. 0 = qualquer descida dispara.
• Limiar de alerta ao comerciante: receba um e-mail quando um produto atinge N subscritores ativos. 0 desativa.
• E-mail do comerciante: destinatário do alerta acima (por defeito: e-mail da loja).
• Retenção (dias): limpeza automática dos subscritores cancelados/notificados há mais de N dias. 180 por defeito, 0 desativa.

Funcionamento do lado do cliente

Inscrição

O formulário está sempre visível na página de produto. O cliente introduz o seu e-mail e escolhe:

• Qualquer descida: será avisado na primeira redução abaixo do preço apresentado no momento da inscrição (sujeito ao limiar mínimo configurado).
• Quando atingir: introduz um preço alvo, obrigatoriamente inferior ao preço atual. O alerta só parte quando o preço desce até esse nível ou abaixo.

Se o produto tiver combinações, a combinação selecionada é capturada automaticamente, e atualizada se o cliente mudar de combinação antes de confirmar.

Confirmação (duplo opt-in)

Com o duplo opt-in ativo, o subscritor recebe um e-mail de confirmação. O alerta permanece no estado pending até ao clique, e passa depois a active. Sem duplo opt-in, o alerta fica ativo de imediato.

Notificação

Quando é detetada uma descida elegível, o subscritor recebe um e-mail com o preço antigo riscado, o novo preço, a percentagem de redução, o montante poupado e uma ligação direta para o produto. O seu estado passa a notified: não receberá outro e-mail para a mesma inscrição.

Deteção das descidas: os três gatilhos

O módulo deteta as descidas de preço por três canais complementares:

1. Hook actionObjectProductUpdateAfter: dispara a cada gravação de um produto no back-office. Cobre as alterações manuais de preço com latência nula.
2. Hook actionUpdateProductAttribute: dispara na alteração de uma combinação. Cobre as alterações de preço por combinação.
3. Comando CLI bin/scan-prices.php: a ligar num cron. Indispensável para os preços específicos programados (specific prices com data), que se ativam sem disparar nenhum hook.

Configuração do cron

*/30 * * * * php /caminho/para/a/sua/loja/modules/dfpricealert/bin/scan-prices.php --shop=1 >> /var/log/dfpricealert.log 2>&1

O parâmetro --shop é opcional (loja por defeito caso contrário). O comando mostra o número de alertas enviados e o tempo de execução.

Seguimento de conversões

No hook actionOrderStatusPostUpdate, o módulo percorre cada linha da encomenda e procura um subscritor no estado notified correspondente ao trio (e-mail do cliente, id do produto, id da combinação). Em caso de correspondência, o subscritor passa a purchased e o id_order é registado.

A correspondência aceita quer a combinação exata, quer uma inscrição genérica (combinação 0): os produtos sem combinações e as inscrições «produto principal» são portanto corretamente atribuídos. O seguimento funciona também em checkout como convidado, porque a correspondência é feita por e-mail.

Painel de administração

O separador Catálogo → Price Alerts mostra:

• 6 KPI: subscritores ativos, notificados, convertidos, taxa de conversão, descida média aceite, receita recuperada.
• Produtos com forte potencial: top 10 dos produtos por número de subscritores ativos, com preço médio de inscrição. É a sua lista de candidatos prioritários para uma promoção dirigida.
• Lista de subscritores: filtrável por estado, e-mail e produto, paginada a 25 linhas.
• Ações: analisar todos os produtos imediatamente, limpar as entradas antigas, exportar a lista completa em CSV.

Ciclo de vida de um subscritor

Cada inscrição passa pelos seguintes estados:

• pending: inscrito, à espera de confirmação (duplo opt-in).
• active: alerta ativo, vigiado pelas análises.
• notified: e-mail de descida enviado. Estado final, salvo compra.
• purchased: encomenda detetada após notificação, conversão atribuída.
• unsubscribed: cancelamento através da ligação presente em cada e-mail.

Cada transição é registada na tabela df_pricealert_event (pista de auditoria completa).

E-mails

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

• confirm: confirmação do duplo opt-in com botão de ativação.
• alert: notificação de descida: preço antigo riscado, novo preço em destaque, poupança em euros e em percentagem, botão para o produto.
• merchant: notificação ao comerciante quando um produto ultrapassa o limiar de subscritores ativos.

O e-mail parte no idioma do subscritor (o da página no momento da inscrição), com recurso automático ao inglês se o idioma não estiver disponível. Os modelos são personalizáveis em modules/dfpricealert/mails/<iso>/.

RGPD

• Duplo opt-in por e-mail antes da ativação (ativo por defeito).
• Tokens criptográficos de 32 bytes (random_bytes) únicos por subscritor para a confirmação e o cancelamento.
• Ligação de cancelamento num clique em cada e-mail.
• Limpeza automática configurável dos dados antigos (minimização dos dados).
• Nenhum dado enviado a serviços de terceiros: tudo fica no seu servidor.

Resolução de problemas

Os alertas não partem

• Verifique que o subscritor está no estado active (não pending: o duplo opt-in exige a confirmação).
• Verifique o limiar mínimo de descida: uma descida de 3% com um limiar de 5% não dispara.
• Em modo preço alvo, o preço tem de atingir ou passar abaixo do alvo, não basta descer.
• Para os preços específicos programados, verifique que o cron está a correr (consulte o registo).
• Teste o envio de e-mail do PrestaShop em geral (Parâmetros avançados → E-mail → Teste).

Erros na inscrição

O módulo regista todos os erros em Parâmetros avançados → Registos com o prefixo [dfpricealert]. O formulário mostra além disso os erros de servidor detalhados diretamente por baixo do botão (estado HTTP e excerto da resposta), o que acelera o diagnóstico.

O formulário não aparece

• Verifique a posição configurada: alguns temas não implementam displayProductAdditionalInfo; mude para displayProductActions.
• Esvazie a cache do PrestaShop (Parâmetros avançados → Desempenho).

Desinstalação

A desinstalação elimina as duas tabelas do módulo (subscritores e eventos incluídos), os hooks, o separador de administração e todas as chaves de configuração. Exporte o CSV antes, se quiser conservar o histórico.