A busca é utilizada para encontrar produtos através de uma consulta por termo ou id de produto. A busca personalizada utiliza diversas informações de sua loja, como dados de navegação e consumo para encontrar os produtos mais adequados à consulta de cada usuário. Esta request realiza uma consulta por um termo, id de produto ou conjunto de ids de produtos, retornando os produtos e features complementares resultantes.
Como fazer a consulta?
Para realizar uma consulta, você pode passar um termo para a consulta
https://api.linximpulse.com/engage/search/v3/search?apiKey=<loja>&secretKey=<secretKey>&terms=celular+samsung
Você também pode passar um ou vários ID de produto para a consulta
https://api.linximpulse.com/engage/search/v3/search?apiKey=<loja>&secretKey=<secretKey>&pids=P123458&pids=P987753
Para filtrar as consultas, realizar ações de paginação ou outras interações com a API, fornecemos links prontos, basta utilizá-los, incluindo sua secretKey.
Como é a resposta?
Os produtos retornados estarão no campo **products**. O formato/conteúdo de cada produto no **products **está listado acima na seção **Parameters** na explicação do campo **productFormat**. É importante notar que alguns valores retornados no **products** são opcionais, ou seja, nem sempre serão retornados, por exemplo o campo **customBusiness**.
Existem outros campos que são retornados conforme a resposta para aquela consulta. Os principais campos estão descritos abaixo.
| Campo | Descrição |
|---|---|
| suggestions | Algumas consultas podem possuir sugestões de consultas relacionadas. |
| filters | Lista de filtros retornados pela consulta. Cada filtro pode ser de um tipo, identificaod no campo type. Os valores possíveis são:
|
| quickFilters | Permite que algumas consultas exibam de maneira destacada um conjunto pré-determinado de filtros para que o usuário possa direcionar o seu foco. Recomenda-se o uso em consultas muito genéricas. Por exemplo, a consulta "samsung" pode ser feita por um usuário buscando tvs, notebooks ou celulares. Neste caso, a utilização de um quickFilter ajudaria o usuário a direcionar o seu interesse. O retorno é uma lista de opções que o usuário pode selecionar para filtrar os produtos retornados pela consulta. |
| banners | Banner a ser exibido na página de resultados. Algumas consultas podem ter banners associados a ela, neste caso eles serão retornados neste campo. |
Alguns campos existentes na resposta possuem valores padrões. Abaixo descrevemos alguns desses campos.
O campo queries traz informações referentes à consulta realizada, como por exemplo a consulta original e normalizada. Um dos campos retornados é o queryType, onde você pode identificar qual o tipo de consulta foi realizada. Os possíveis valores retornados estão descritos abaixo. Observe, também, o código de resposta da pode variar conforme este tipo.
| Valor | Code | Descrição |
|---|---|---|
| found | 200 | Houve ao menos um produto com os termos pesquisados. |
| corrected | 200 | Foi identificado um erro de digitação na consulta enviada e ela foi corrigida (ex.: "notebok" pode ser corrigido para "notebook"). |
| aproximated | 200 | Nenhum produto possui todos os termos da consulta, busca-se então por produtos com parte dos termos consultados. (ex.: "notebook sony vaio" pode ser corrigido para "notebook sony"). |
| notfound | 404 | Não houve nenhum produto com os termos pesquisados. |
| redirect | 302 | Redirecionamento. A consulta está cadastrada como redirect e deve enviar o usuário a outra página, nesse caso são retornados apenas os campos "queries.queryType" e "queries.original". |
O campo pagination traz informações referentes à paginação. Em casos onde o resultado possui muitos produtos, estes são segmentados por páginas. Este campo é um objeto que pode possuir os campos abaixo:
| Campo | Descrição |
|---|---|
| first | Url da primeira página de resultados. Por padrão seu número é 1. |
| last | Url da última página de resultados. |
| next | Url da próxima página de resultados. Por padrão seu valor é a página atual+1. |
| previous | Url da página anterior de resultados. Por padrão seu valor é a página atual-1 |
Tracking de eventos
Eventos de click
Cada produto do resultado da busca contém um campo chamado clickUrl.
Este campo fornece uma URL da API de Busca, na rota /clicks que deverá ser usada para registrar todos os eventos de click dos usuários da aplicação com os produtos do resultado da busca. É por meio destes registros que geramos métricas de performance da busca, além de melhorar as estratégias para acertar em cheio cada resultado..
{
id: "10005354",
name: "oculos",
price: 249.98,
oldPrice: 249.98,
url: "...",
images: {
template-418481: "...",
1000x1000: "..."
},
installment: {
count: 6,
price: 41.66
},
status: "AVAILABLE",
clickUrl: "/search/v3/clicks?apikey=loja&trackingId=eyJzZWFyY2hJZCI6IjQ1NTE5MDkwLTQxMDktNGM1MC1hNGZmLTYwMGM0YTZhOWVkZiIsIm9yaWdpbiI6InNlYXJjaCIsInByb2R1Y3QiOnsicmFua2luZyI6MSwicGlkIjoiMTAwMDUzNTciLCJza3VzIjpbXX19",
categories: [
{
id: "ÓCULOS DE SOL",
name: "ÓCULOS DE SOL",
parents: [ ],
used: true
}
],
tags: [
{
id: "oculos_de_sol",
name: "ÓCULOS DE SOL",
parents: [ ]
}
],
specs: { },
created: "2018-08-02 11:52:51",
brand: null,
collectInfo: {
skuList: [ ],
productId: "10005354"
},
cId: "84",
iId: 10641,
skus: [
{
sku: "2067712",
specs: { },
properties: {
stock: 1,
name: "oculos",
oldPrice: 249.98,
url: "...",
price: 249.98,
eanCode: "7909140245889",
status: "available",
details: {
referenceId: "7909140245889",
measurement: {
unit: "un",
multiplier: 1
}
},
installment: {
price: 41.66,
count: 6
},
images: {
template-418481: "...",
1000x1000: "..."
}
}
}
],
details: {
productReference: [
"..."
],
clusterHighlights: [
{
178: "Mais Vistos",
192: "Todos produtos",
246: "lightbox-oculos",
247: "modal-oculos"
}
],
brand: [
"..."
],
referenceId: [
"7909140245889"
],
measurement: [
{
unit: "un",
multiplier: 1
}
],
categoryName: [
"ÓCULOS DE SOL"
]
},
description: "..."
}
Ao clickUrl deverá ser adicionada a URL base da API no início e ao final os parâmetros exigidos pela rota de click. Detalhes dos parâmetros da rota de click podem ser encontados na documentação /clicks
Por exemplo:
https://api.linximpulse.com/engage/search/v3/clicks?apikey=loja&trackingId=eyJzZWFyY2hJZCI6IjQ1NTE5MDkwLTQxMDktNGM1MC1hNGZmLTYwMGM0YTZhOWVkZiIsIm9yaWdpbiI6InNlYXJjaCIsInByb2R1Y3QiOnsicmFua2luZyI6MSwicGlkIjoiMTAwMDUzNTciLCJza3VzIjpbXX19&deviceid=teste&source=desktop
É recomendado que este evento seja disparado somente depois que o usuário acessar a página do produto, evitando assim que o browser cancele a requisição caso a página de produto seja carregada antes que o disparo tenha sido concluído.
A Coleta de Dados é parte essencial da implementação, pois sem ela não haverá aumento de performance nos resultados de busca e nem métricas disponíveis para você acompanhar o desempenho em produção.