Instalar na loja PrestaShop

O módulo, o handshake, a primeira indexação e a ativação do painel de pesquisa, pela ordem certa.

O módulo Buskara para PrestaShop faz três coisas: liga a loja à sua conta, mantém o catálogo indexado, e injeta o script do painel de pesquisa nas páginas. Instalar o módulo não muda nada na loja: o painel de pesquisa só aparece aos visitantes no fim deste guia, quando o catálogo já estiver indexado.

1. A chave de API

A conta nasce sem nenhuma, e a primeira aparece sozinha: a seguir ao registo, o Buskara leva-o por três passos (descarregar o módulo, copiar a chave, esperar pela loja) e é no segundo que ela é emitida e mostrada. Se fechou esse ecrã antes de a copiar, volte a /ativar e peça uma nova.

A chave completa (bk_live_…) aparece uma única vez: copie-a nesse momento. A lista mostra depois só o prefixo e quando foi usada pela última vez. Para emitir mais (uma por loja, por exemplo), abra o perfil da conta no painel, separador Integrações.

Cada chave da lista tem três destinos possíveis. Revogar corta no imediato tudo o que a estivesse a usar, e tem volta: uma chave revogada reativa-se no botão ao lado, com o mesmo valor de antes. Apagar é que não tem volta, porque o valor não está guardado em lado nenhum; se apagar a chave que a loja usa, emita outra e volte a colá-la no módulo.

2. Instalar e ligar

1. Instale o módulo Buskara no back office do PrestaShop e abra a configuração.
2. Enquanto a loja não estiver ligada, o módulo mostra um ecrã de boas-vindas com dois campos: cole aí a chave de API e confirme o endereço do Buskara (https://buskara.com).
3. Carregue em Ligar a loja.

O módulo não gera chaves nem as inventa: recebe a que a sua conta emitiu. Quem instalar o módulo antes de ter conta encontra nesse mesmo ecrã o botão para a criar.

Este último clique é o handshake: a loja apresenta-se (URL, versões, lojas, línguas e moedas) e recebe de volta o seu identificador, a chave pública de pesquisa e um motor de pesquisa por loja × língua × moeda. É neste momento que a loja aparece no painel, em Pesquisa → Lojas; não há nada para criar à mão. É também a partir daqui que a configuração do módulo passa a mostrar tudo o resto: estado, indexação, aparência e partilha de dados.

O número de lojas ligadas é um limite do plano. Se o handshake for recusado por isso, a mensagem diz o plano e o limite; voltar a ligar uma loja que já existe nunca é bloqueado.

3. A primeira indexação

Clique em Reindexar tudo no módulo. O catálogo segue em lotes, e no painel (Pesquisa → Lojas) vê o progresso: Em fila, A indexar… (enviados / total) e por fim Em dia, com o total de documentos.

Num catálogo grande, o botão pode esbarrar no tempo máximo de execução do PHP. Para esses casos o módulo traz uma alternativa por linha de comandos, que não tem esse limite:

php modules/buskara/cli/reindex.php

Depois da primeira indexação completa, o dia-a-dia trata-se sozinho por três vias:

• Tempo real: guardar, apagar ou mudar o stock de um produto empurra a alteração na hora.
• Sincronização periódica: a plataforma pede a reindexação à loja em ciclos regulares. Para isso, o endereço https://a-sua-loja/module/buskara/sync tem de estar acessível do exterior; atenção a firewalls e basic-auth em lojas de pré-produção.
• Manual: o botão ou o CLI, quando quiser forçar.

4. Testar sem mostrar a ninguém

Antes de ligar o painel de pesquisa para todos, use a caixa IPs de debug no módulo: com o seu IP lá dentro, o painel de pesquisa só aparece para si, e pode experimentar na loja em produção à vontade.

O reverso é importante: enquanto houver IPs nessa caixa, mais ninguém recebe o painel de pesquisa. Se um dia "a pesquisa desapareceu da loja", este é o primeiro sítio onde olhar.

5. Ligar o painel de pesquisa

A primeira indexação completa que ponha produtos no índice liga o painel de pesquisa por si. A partir desse momento, cada página da loja carrega uma única tag de script, e a pesquisa passa a ser a do Buskara: a barra do tema continua no sítio, mas quem responde somos nós.

Até lá o interruptor do painel de pesquisa está desligado de propósito. Ligar a loja quando o índice ainda está vazio dava aos seus clientes uma pesquisa que não encontra nada, que é pior do que não a ter. O interruptor fica na configuração do módulo, e é seu: se o desligar, fica desligado, e nenhuma indexação a seguir o volta a ligar sem si.

Se o seletor por omissão (input[name='s']) não apanhar a barra do seu tema, ajuste o seletor da barra de pesquisa. Em temas com pesquisa própria no telemóvel, é normal ser preciso preencher também os seletores de botões que abrem a pesquisa e esconder durante a pesquisa; isso afina-se na ficha da loja no painel, e está explicado no guia da aparência e integração no tema.

As restantes opções do módulo

• Preços com IVA e tamanho de imagem: como os produtos chegam ao índice.
• Produtos sem stock: indexar na mesma, despromover nos resultados, ou esconder.
• Dados que a loja partilha: três sinais opcionais que melhoram o produto. O volume de vendas por produto alimenta a ordenação "mais vendidos" e a deteção de best-sellers invisíveis; o preço de custo dá margens nas analytics; as encomendas ligam a pesquisa à receita (ver o guia de analytics). Mudar a partilha de vendas ou de custo pede uma reindexação completa para o índice refletir; o módulo avisa.
• Artigos e conteúdo: indexar também o blog/CMS num motor separado, que aparece nos resultados sem roubar lugar aos produtos.
• Estrelas: de onde vêm as avaliações mostradas nos cards (deteção automática dos módulos habituais).

Se algo correr mal

• A loja não aparece no painel: o handshake falhou. Confirme o endereço, a chave (sem espaços a mais) e volte a carregar em Ligar a loja.
• "A indexar" nunca chega ao fim: use o CLI; o botão esbarra no tempo de execução do PHP em catálogos grandes.
• O painel de pesquisa não aparece: por esta ordem, o interruptor do painel de pesquisa está ligado? A caixa de IPs de debug está vazia? A loja está Ativa (e não Em pausa) no painel do Buskara?
• O painel de pesquisa aparece mas a barra do tema continua a responder: o seletor da barra não está a apanhar o input certo; inspecione o tema e ajuste-o.

Desinstalar o módulo limpa toda a configuração local. O índice do lado do Buskara fica; a loja é que deixa de o alimentar.