Documentação Pesquisa Sem Resultados: Página de Recuperação e Alertas

Apresentação

O módulo Pesquisa Sem Resultados (dfzerosearch) entra em ação quando uma pesquisa na sua loja não encontra nada. Em vez de uma página vazia, o visitante vê uma página de recuperação: o destino que escolheu para essa pesquisa, os produtos cuja referência se parece com a escrita, a pesquisa corrigida, uma pesquisa mais ampla, os mais vendidos da categoria deduzida e um formulário «avise-me».

No back-office, cada pesquisa perdida é contabilizada. Associa-a a um produto, uma categoria, outra pesquisa ou um URL, com uma regra exata, «contém» ou curinga. O módulo mede depois o que essas recuperações rendem: taxa de recuperação, encomendas e receita sem IVA.

Instalação e atualização

Primeira instalação

1. Abra Módulos > Gestor de módulos e clique em Carregar um módulo.
2. Selecione o arquivo dfzerosearch.zip.
3. O módulo cria as suas tabelas, o seu menu de administração e a configuração predefinida. Fica ativo de imediato.
4. Copie o URL da tarefa agendada apresentado na página de configuração e agende-o de hora a hora (ver abaixo).

Atualização a partir de uma versão anterior

Carregue o novo ZIP por cima do antigo, sem desinstalar. O PrestaShop executa os scripts de atualização: novas colunas, novas definições com o valor predefinido e limpeza da cache do módulo. As pesquisas perdidas, regras, subscritores e estatísticas são mantidos.

Configuração

A página Configurar começa com atalhos para os três ecrãs do módulo, seguidos de três painéis de definições e do painel da tarefa agendada.

Rescue page

• Enable module: ativa ou suspende a deteção e a página de recuperação.
• Typo correction (“Did you mean…”): corrige erros de escrita palavra a palavra com base no índice de pesquisa e mostra os produtos correspondentes.
• Similar references: para uma referência que não existe no catálogo, mostra os produtos cuja referência começa da mesma forma. Hífenes, espaços e maiúsculas são ignorados, as referências de combinações são incluídas.
• Partial match: quando uma pesquisa longa falha por causa de uma palavra («botas couro tamanho 45»), mostra os resultados da pesquisa mais curta mais próxima.
• Best sellers of the guessed category: compara a pesquisa com os nomes das categorias, subcategorias incluídas.
• Global best sellers fallback: só aparecem se nenhum outro bloco encontrou nada. Sem vendas, são usadas as novidades.
• “Notify me” form: o visitante deixa o email para ser avisado quando a sua pesquisa encontrar um produto.
• Use the theme product miniatures: os produtos aparecem como nas páginas de categoria (adicionar ao carrinho, vista rápida, etiquetas). Desativado, o módulo usa os seus cartões compactos.
• In-stock products only: oculta os produtos esgotados em todos os blocos.
• Custom message (por idioma): texto apresentado no topo da página de recuperação, por exemplo um número de telefone ou uma ligação para encomendas especiais. %query% é substituído pelas palavras pesquisadas.
• Popular searches: etiquetas clicáveis com pesquisas que funcionam. Introduza a sua própria lista por idioma ou deixe vazio para usar as pesquisas frequentes com resultados.
• Products per block: de 1 a 24 (8 por predefinição).

Tracking and data

• Minimum query length: abaixo deste valor, a pesquisa não é registada nem recuperada (2 por predefinição).
• Treat approximate-only results as lost: a pesquisa aproximada nativa do PrestaShop devolve muitas vezes produtos sem relação para uma palavra desconhecida. Quando uma pesquisa só encontra esse tipo de resultado, é contabilizada como perdida e o bloco de recuperação aparece por cima.
• Ignore bots and crawlers: as pesquisas de motores de busca, ferramentas SEO e scripts não são registadas.
• Attribution window (days) (7 por predefinição): uma encomenda feita neste prazo após uma recuperação é atribuída à pesquisa e ao bloco que trouxeram o visitante de volta (último contacto).
• Cache rescue results: guarda o trabalho de pesquisa durante 15 minutos por pesquisa. Preços e stock continuam em tempo real. A cache é limpa assim que altera uma definição ou uma regra.
• Retention (days) (180 por predefinição): as pesquisas perdidas não vistas durante este período e as subscrições já avisadas são apagadas pela tarefa agendada. 0 guarda tudo. Um botão permite apagar de imediato.

Automation

• Automatic notify-me emails: os subscritores recebem o aviso assim que a sua pesquisa recebe uma regra ativa ou a pesquisa volta a encontrar produtos.
• Weekly digest: de 7 em 7 dias, pesquisas perdidas, taxa de recuperação e principais pesquisas perdidas, enviadas por email.
• Digest recipient: vazio, é usado o email da loja.

Tarefa agendada

O painel Scheduled task (cron) apresenta um URL protegido por token. Chame-o de hora a hora a partir do cPanel, Plesk ou de qualquer serviço de cron, por exemplo:

0 * * * * curl -s "https://www.a-sua-loja.pt/module/dfzerosearch/cron?token=..." > /dev/null

A tarefa envia os avisos automáticos, aplica o período de conservação e envia o relatório semanal. O painel indica a data da última execução, o botão Run now lança a tarefa manualmente e Generate a new token substitui o URL se este tiver sido divulgado. Em multiloja, agende uma tarefa por loja com o URL apresentado no contexto de cada loja.

A página de recuperação

Quando a grelha de resultados está vazia, um script carrega a página de recuperação por AJAX. As pesquisas que encontram produtos não ficam mais lentas. Os blocos aparecem por esta ordem, sem produtos repetidos entre blocos:

1. A sua regra: se uma regra ativa corresponder à pesquisa, o seu destino é destacado. Em modo de redirecionamento, o visitante chega diretamente ao destino. Um sinónimo mostra também os seus produtos.
2. Referências semelhantes: produtos da mesma família de referência.
3. «Queria dizer…»: a pesquisa corrigida e os seus produtos, com ligação para a pesquisa corrigida. Este bloco só aparece se os blocos anteriores não mostraram nada.
4. Correspondência parcial: resultados da pesquisa encurtada, só se ainda nada tiver sido encontrado.
5. Mais vendidos da categoria deduzida.
6. Mais vendidos da loja: apenas em último recurso.

A mensagem personalizada aparece acima dos blocos; as pesquisas populares e o formulário «avise-me», abaixo.

Referências semelhantes

Muitos clientes pesquisam um produto pela referência exata. Quando essa referência não existe no catálogo, o módulo propõe os produtos da mesma família.

• O módulo identifica na pesquisa a palavra que parece uma referência: pelo menos 5 caracteres, dos quais pelo menos 2 algarismos.
• Compara-a com as referências de produtos e combinações, ignorando hífenes, espaços, pontos e maiúsculas. M91650-0005, m91650 0005 e M916500005 são tratados da mesma forma.
• Só são mantidos os produtos com um início de referência comum suficientemente longo (pelo menos 5 caracteres e 60% da referência pesquisada). Os mais próximos aparecem primeiro.
• Exemplo: uma pesquisa por M91650-0005 mostra M91650-0001 e M91650-0002, mas não M91651-0003.

Regras: associações e sinónimos

O ecrã Mappings & synonyms lista as suas regras. Para criar uma, clique em Add a mapping ou use a ação Map de uma pesquisa perdida, que pré-preenche o formulário.

Tipos de correspondência

• Exata (exact): a pesquisa tem de ser idêntica à regra. Maiúsculas, acentos e espaços a mais são ignorados.
• Contém (contains): a regra tem de aparecer como palavra ou sequência de palavras na pesquisa. Hífenes, barras, pontos e outros separadores contam como espaços: a regra m91651 aplica-se a M91651-0003.
• Curinga (wildcard): * substitui qualquer sequência de caracteres e ? um único carácter. M91650* cobre M91650-0001, M91650-0007 ou m916500009, mas não M91659-0001. Qualquer regra que contenha * ou ? é guardada automaticamente como curinga.

Prioridades

Quando várias regras correspondem a uma pesquisa, ganha a mais precisa: uma regra exata passa à frente de uma curinga, que passa à frente de uma «contém». Com o mesmo tipo, uma regra de um idioma específico passa à frente de uma regra «todos os idiomas», e depois ganha a regra mais longa.

Destinos e modos

• Product: pesquisa por nome, referência ou ID no formulário.
• Category.
• Synonym (other search): outras palavras que dão resultados («sweatshirt» para «camisola»). Os produtos dessa pesquisa aparecem na página de recuperação.
• Custom URL: URL absoluto ou caminho que começa por uma barra.

Cada regra funciona em modo Suggest (destino destacado na página de recuperação) ou Redirect (o visitante chega diretamente ao destino). Uma regra pode aplicar-se a um idioma específico ou a todos.

Importação e exportação CSV

O painel Import / export (CSV) do ecrã de regras importa até 5000 linhas e exporta todas as regras. Separador ; ou ,, cabeçalho opcional. Colunas:

query ; match ; language ; type ; target ; mode ; active
M91650* ; wildcard ; all ; category ; 12 ; redirect ; 1
camisola ; exact ; pt ; search ; sweatshirt ; suggest ; 1
M91651 ; contains ; all ; product ; M91651-0003 ; suggest ; 1

• match: exact, contains ou wildcard (exact por predefinição; curinga detetado automaticamente se a regra contiver * ou ?).
• language: código ISO, ou vazio, * ou all para todos os idiomas.
• type: product, category, search ou url.
• target: ID ou referência de produto, ID de categoria, palavras a pesquisar ou URL.
• mode: suggest ou redirect (suggest por predefinição). active: 1 ou 0 (1 por predefinição).

Uma regra existente com a mesma pesquisa e o mesmo idioma é atualizada. O relatório de importação indica as linhas criadas, atualizadas e rejeitadas com o respetivo número.

Alertas «avise-me»

O formulário da página de recuperação tem uma caixa de consentimento desmarcada por predefinição e um campo armadilha contra bots. Para um cliente com sessão iniciada, o email já vem preenchido. Os pedidos são listados no ecrã Notify-me requests com o respetivo estado.

Com a tarefa agendada e a opção Automatic notify-me emails, o subscritor recebe o email dfzerosearch_alert assim que a sua pesquisa recebe uma regra ativa ou a pesquisa volta a encontrar produtos. Também pode enviá-lo manualmente com a ação Notify de uma regra. Cada email inclui uma ligação para cancelar a subscrição.

Painel e receita recuperada

O ecrã Lost queries mostra os números dos últimos 30 dias: pesquisas perdidas, taxa de recuperação, encomendas após recuperação, receita recuperada sem IVA, novas subscrições e emails pendentes. Um gráfico compara dia a dia as pesquisas perdidas e recuperadas, outro mostra os cliques por bloco de recuperação (regra, referências semelhantes, correção, correspondência parcial, categoria, mais vendidos, pesquisas populares).

A lista de pesquisas perdidas está ordenada por volume. Cada linha oferece Map, Ignore / restore e, quando foi encontrada uma correção, Create a synonym from this correction. A tabela Latest orders after a rescue indica a pesquisa e o bloco creditados.

Relatório semanal

De 7 em 7 dias, a tarefa agendada envia o email dfzerosearch_digest: pesquisas perdidas, visitantes recuperados, taxa de recuperação, encomendas e receita sem IVA após recuperação, novos pedidos «avise-me» e pesquisas perdidas mais frequentes. Se nada aconteceu durante a semana, nenhum email é enviado.

RGPD

• Consentimento explícito: caixa desmarcada por predefinição e texto de consentimento claro.
• Módulo RGPD oficial: o módulo está registado no psgdpr. A exportação e a eliminação dos dados de um cliente incluem os seus pedidos «avise-me».
• Cancelamento: uma ligação em cada email.
• Conservação: eliminação automática de pesquisas antigas e subscrições já avisadas.
• Alojamento próprio: nenhum dado é enviado para serviços de terceiros.

Compatibilidade e informação técnica

• PrestaShop 8.0 a 9.x, multiloja.
• Interface e emails em inglês, francês, espanhol, alemão e italiano.
• Hooks: actionSearch, actionFrontControllerSetMedia, actionValidateOrder, registerGDPRConsent, actionDeleteGDPRCustomer, actionExportGDPRData.
• Tabelas: dfzerosearch_query, dfzerosearch_mapping, dfzerosearch_alert, dfzerosearch_stat, dfzerosearch_session, dfzerosearch_conversion.
• Menu AdminDfZeroSearch em Módulos, com três ecrãs: pesquisas perdidas, associações e sinónimos, pedidos «avise-me».
• Controladores front: rescue (página de recuperação, JSON), cron (tarefa agendada, token) e unsubscribe.
• Sem dependências: sem Composer, JavaScript sem jQuery, sem serviço externo.

Resolução de problemas

• A página de recuperação não aparece: verifique se o módulo está ativo e se a pesquisa devolve mesmo zero resultados, e limpe a cache do PrestaShop e do navegador. Com um tema muito personalizado, contacte-nos indicando o nome do tema.
• Uma pesquisa mostra produtos sem relação e não é contabilizada como perdida: ative Treat approximate-only results as lost.
• Nenhuma referência semelhante: a palavra pesquisada precisa de pelo menos 5 caracteres com 2 algarismos, e têm de existir produtos ativos, visíveis na pesquisa, com o mesmo início de referência.
• Uma regra curinga não se aplica: verifique se está ativa, no idioma certo, e se nenhuma regra exata tem prioridade. Teste-a sem separador (M91650*) se os clientes escreverem a referência de várias formas.
• Nenhuma correção proposta: a correção só sugere palavras presentes no índice; reconstrua o índice de pesquisa do PrestaShop se o catálogo mudou muito.
• Os emails automáticos ou o relatório não são enviados: verifique a data da última execução da tarefa agendada e a configuração de email do PrestaShop. O botão Notify mostra um erro explícito se o envio falhar.
• O painel continua vazio: verifique o comprimento mínimo da pesquisa e teste a partir de um navegador normal, já que os bots são ignorados.