Live Search & Autocomplete — Documentação

Instalação

Requisitos

Magento 2.4.x (Open Source ou Adobe Commerce), PHP 8.1–8.5. Funciona com qualquer mecanismo de busca que o Magento suporte (OpenSearch, Elasticsearch ou MySQL). Compatível com os temas Hyvä e Luma. Requer o gratuito codingrow/module-core. Nenhum provedor de IA ou chave de API é necessário — o módulo é busca de catálogo pura.

Configuração inicial

Instale via Composer, ative o módulo e execute a atualização/compilação padrão:

composer require codingrow/module-live-search-autocomplete
bin/magento module:enable Codingrow_LiveSearchAutocomplete
bin/magento setup:upgrade && bin/magento setup:di:compile
bin/magento cache:flush

Depois vá em Lojas → Configuração → Codingrow → Live Search & Autocomplete, cole sua chave de licença, defina Ativar = Sim e limpe o cache.

Configuração

Todas as opções ficam em Lojas → Configuração → Codingrow → Live Search & Autocomplete.

Desinstalação

Defina Ativar = Não para desligá-lo sem remover nada, ou remova o módulo por completo:

bin/magento module:disable Codingrow_LiveSearchAutocomplete
composer remove codingrow/module-live-search-autocomplete
bin/magento setup:upgrade && bin/magento cache:flush

Busca & sinônimos

Como funciona

Um script pequeno e independente de tema se conecta ao seu campo de busca existente (ele detecta as barras de busca do Hyvä e do Luma automaticamente). Enquanto o cliente digita, ele aplica debounce à entrada e pede ao módulo os produtos correspondentes, então renderiza um dropdown com miniatura, nome, preço e qualquer desconto para cada resultado, além de um link "ver todos os resultados" para a página de busca completa. Cada resultado tem link direto para a página do produto. Os resultados respeitam a visibilidade do produto, o estoque e o escopo da loja.

Desempenho

As sugestões são obtidas do próprio mecanismo de busca indexado do Magento — o mesmo mecanismo que alimenta a página de resultados (OpenSearch, Elasticsearch ou MySQL) — através da requisição nativa quick_search_container. Como a correspondência é feita pelo índice e não pela varredura do banco de dados, o tempo de resposta permanece baixo e não cresce com o tamanho do catálogo. Em uma loja ao vivo de 67.000 produtos, as sugestões retornam em cerca de um segundo e permanecem estáveis conforme o catálogo cresce.

Busca em campos estendidos

Se o autocompletar busca apenas o nome/SKU ou também a descrição e outros campos é controlado pelo próprio Magento, por atributo — não por um interruptor do módulo. Em Lojas → Atributos → Produto, cada atributo tem um sinalizador "Usar na Busca" e um peso de busca. Por padrão, name, sku, description e short_description são pesquisáveis, então o autocompletar já os busca. Para incluir ou excluir um campo, ou para fazer um deles pesar mais, altere as configurações de busca desse atributo e reindexe — o autocompletar segue a mesma configuração da página de resultados, e permanece rápido independentemente do tamanho do catálogo.

Search Synonyms nativos

O módulo sempre usa os Search Synonyms nativos do Magento. Adicione ou edite-os no admin padrão em Marketing → SEO & Search → Search Synonyms; o autocompletar os capta imediatamente. Quando uma consulta não retorna nada, o módulo a expande com os sinônimos correspondentes e tenta novamente.

Sinônimos do AI Personal Shopper

Se o módulo Codingrow AI Personal Shopper também estiver instalado (opcional, dependência suave), o autocompletar acessa adicionalmente seu registro de sinônimos autoaprendidos — os termos regionais, de dialeto e com erros de ortografia que o assistente aprendeu a partir de conversas reais. Isso faz com que até buscas "erradas" correspondam aos produtos certos. Ative-o com Usar sinônimos do AI Personal Shopper = Sim. Sem esse módulo, o autocompletar funciona perfeitamente apenas com os sinônimos nativos.

Uso

Como aparece

O dropdown é injetado abaixo da sua barra de busca existente e estilizado para não atrapalhar o seu tema. Cada linha mostra a miniatura do produto (se ativada), o nome e o preço com qualquer desconto; a cor de destaque (preços e o link "ver todos os resultados") é configurável. A navegação pelo teclado (teclas de seta e Enter) e o layout mobile são tratados automaticamente.

Barra de busca fixa

Transforme a busca da loja em um cabecalho compacto sempre visivel: quando o cliente rola a pagina, uma barra fina se fixa no topo com o logo da loja, o menu, os links de conta e carrinho e — acima de tudo — o campo de busca com o mesmo autocompletar em tempo real. A busca fica a um olhar de distancia em cada pagina, como fazem os grandes marketplaces. Independente do tema: funciona em Hyva e Luma e reutiliza a acao de busca nativa, entao envio e autocompletar se comportam exatamente como a busca normal.

No desktop a barra e uma unica linha. No celular nunca ultrapassa duas linhas — menu hamburguer, logo, conta e carrinho na primeira linha, o campo de busca na segunda — assim cabe em telas pequenas sem empurrar o conteudo. Ela aparece quando o cliente passa de um limite de rolagem configuravel e se esconde novamente no topo.

Ative em Stores → Configuration → Codingrow → Live Search & Autocomplete → Appearance com Sticky search bar = Yes (com um limite de rolagem opcional em pixels). A barra tambem expoe um espaco para o botao de busca com IA do modulo AI Personal Shopper, se instalado.

A barra fixa e o que ela não deve cobrir

Com a barra de busca fixa ativa, passado o limite de rolagem aparece no topo da tela uma barra compacta. Por ser fixa, cobre o que passa embaixo dela: na página do produto costuma ser o título, primeira linha do bloco de compra que o tema mantém à vista. E ficaria coberto pela página inteira, não só de passagem.

Keep pinned content clear of the sticky bar (ativa por padrão) resolve: a barra publica a sua altura medida na propriedade CSS --crls-sticky-h no elemento <html> — 0px enquanto está escondida — e tudo o que está fixado no topo desce exatamente isso, voltando ao lugar quando a barra some. Os links com âncora também chegam abaixo dela. A altura é medida, nunca fixada no código: cerca de 57px no desktop, cerca de 107px abaixo de 768px, onde o campo de busca passa para uma linha própria.

Elementos fixados dentro de um contêiner que realmente rola não são tocados: estão ancorados a esse contêiner, não à janela. Os seus próprios templates podem ler a mesma propriedade: top: calc(1.5rem + var(--crls-sticky-h, 0px)), cujo valor de reserva mantém o deslocamento original onde o módulo não está instalado.

Licença

O módulo usa uma licença por domínio (uma chave de módulo único, ou uma chave de assinatura Codingrow que desbloqueia todos os módulos Codingrow). A chave é verificada localmente: nunca deixa a vitrine lenta e nunca expõe seus dados. O autocompletar não é renderizado sem uma licença válida. A tua licença cobre a versão atual mais 1 ano de atualizações e suporte; podes continuar a usar para sempre as versões cobertas e renovar o suporte (−35%) para atualizar para versões mais recentes.

Resolução de problemas