Widgets de recomendação no site
Um widget é um bloco de produtos pronto para o site: “Você também pode gostar” na página inicial, “Comprados juntos” na página do produto, “Vistos recentemente” no carrinho. Você o configura no OneTrace.pro e cola um código curto no site uma única vez. Depois disso, o tipo, a aparência, as regras de exibição e a ativação mudam sem editar o site.
Para funcionar, são necessários o rastreador instalado (Conexão do site), o catálogo de produtos e os eventos de visualização, carrinho e compra (Recomendações e catálogo de produtos). Criar e alterar widgets é permitido para “Proprietário”, “Administrador” e “Gerente”; os demais veem as configurações e as estatísticas, mas não podem salvar.
Lista de widgets
Abra Site → Widgets. O card de cada widget mostra o status, as estatísticas de 30 dias, a comparação das variantes, se houver, e o código para o site.

O interruptor Exibir no site desativa o widget sem editar o site: o status muda para “Pausado”, e o bloco na página é limpo. Ative de novo, e os produtos voltam. O botão com a lixeira exclui o widget de vez.
Para criar um widget, clique em Criar widget. Para alterá-lo, clique no nome ou no botão com o lápis. As duas ações abrem a página do editor.
Editor de widget
À esquerda ficam as configurações, em quatro seções: Produtos, Aparência, Exibição e Variantes. À direita fica a pré-visualização: ela desenha o widget exatamente como no site, com produtos reais do seu catálogo. Se uma seção tiver um erro, aparece uma marca ao lado do nome dela. Clique em Salvar: as alterações aparecem no site no próximo carregamento da página, sem mudar o código. Se você sair da página com alterações não salvas, o navegador avisa.

O seletor Computador / Celular acima da pré-visualização mostra os dois layouts. No site, o layout se adapta à largura do espaço, e não da tela: em uma coluna estreita, o widget fica igual ao do celular. A fonte e a cor do texto o widget herda do site, se você não definir as suas.
Produtos
| Campo | O que define |
|---|---|
| Nome | nome do widget; visível apenas no painel administrativo |
| O que exibir | tipo de recomendação: Personalizados, Populares, Em alta, Vistos juntos, Comprados juntos, Semelhantes, Vistos recentemente, Hora de repor |
| Categoria | para populares e em alta: id da categoria do catálogo; vazio significa o catálogo inteiro |
| Total de produtos | de 1 a 24 |
| Produto para a pré-visualização | para “Vistos juntos”, “Comprados juntos” e “Semelhantes”: id do produto usado na pré-visualização; vazio significa o primeiro produto em estoque |
Se não houver produtos adequados, a pré-visualização mostra espaços reservados cinza para você avaliar a aparência.
Aparência
| Campo | O que define |
|---|---|
| Título | texto acima dos produtos, por exemplo “Você também pode gostar” |
| Botão | texto do botão no card, por exemplo “Detalhes”; vazio significa sem botão |
| Disposição | Grade ou Carrossel com rolagem |
| Cards por linha | de 1 a 8 |
| Mostrar preço | preço no card |
| Estilos prontos | “Como no site”, “Cards”, “Minimalista”, “Contraste”: preenchem os campos de aparência, que depois podem ser alterados |
| O que o card mostra | marca, preço antigo, selo de desconto, borda e sombra do card |
| Proporções da imagem e Imagem | 1:1, 3:4 ou 4:3; a imagem inteira ou preenchendo o espaço com as bordas cortadas |
| Cores | destaque, fundo do card, fundo da imagem, texto, preço, botão e texto do botão; sem cor, como no site, e o fundo da imagem fica branco |
| Tamanho do texto, Tamanho do título, Título | tamanhos em porcentagem da fonte do site e alinhamento do título |
| Arredondamento dos cantos, Espaço entre cards, Espaçamento interno do card | em pixels |
| Setas do carrossel | botões de rolagem nas laterais do carrossel |
| Celular | cards por linha em tela estreita (de 1 a 3) e um layout próprio, por exemplo carrossel em vez de grade |
| CSS próprio | regras para as classes do widget: .cdp-rec__name, .cdp-rec__price, .cdp-rec__button e outras |
O CSS próprio vale apenas dentro deste widget e não altera o resto da página. Ele não pode carregar recursos externos: @import, url() e construções parecidas são recusadas ao salvar.
Se o projeto tiver vários idiomas, acima do título aparece o seletor Idioma dos textos. No idioma padrão, você preenche o Título e o Botão; nos outros idiomas, as traduções deles; um campo vazio mostra o texto do idioma padrão. O visitante vê o título e o botão no idioma dele, o mesmo que o rastreador envia ao perfil (Idioma do cliente); sem tradução, no idioma padrão. Os preços aparecem no formato do idioma do visitante.
Estilo a partir de uma imagem
O botão Estilo a partir de uma imagem, na seção Aparência, escolhe a aparência com base em uma captura de tela com cards de produtos, do seu site ou de um site de que você goste.
- Clique em Estilo a partir de uma imagem.
- Arraste a imagem, cole-a da área de transferência (Ctrl+V) ou escolha um arquivo: PNG, JPEG ou WebP de até 3 MB.
- Se o widget tiver variantes, escolha a qual delas aplicar o estilo.
- Clique em Ajustar o estilo.
A IA preenche as cores, os tamanhos, os arredondamentos, o layout e o que o card mostra, e acrescenta em CSS próprio o que as configurações não permitem. Cada valor é verificado como na digitação manual, e os inadequados são descartados. O resultado é um rascunho: confira a pré-visualização e salve, ou clique em Desfazer.

A imagem não é armazenada. O ajuste é pago com o saldo do projeto conforme o uso real; se o saldo não for suficiente ou a IA não estiver incluída no plano, o botão fica indisponível, e o motivo aparece abaixo dele.
Exibição

| Campo | O que define |
|---|---|
| Exibir no site | ativação do widget, como na lista |
| Somente nas páginas e Exceto nas páginas | endereços das páginas sem o domínio, um por linha; * significa quaisquer caracteres, por exemplo /catalog/*. Vazio: todas as páginas |
| Dispositivos | todos, apenas computadores ou apenas celulares |
| Visitantes | todos, apenas novos ou apenas recorrentes |
| Somente para membros dos segmentos e Exceto membros dos segmentos | segmentos do visitante; a participação é verificada pelo perfil a cada exibição |
O servidor verifica as regras a cada carregamento do widget. Fora das regras, o espaço na página fica vazio, sem quebrar o layout. As regras são as mesmas dos formulários de inscrição.
Aqui também fica o Código para o site, descrito abaixo.
Variantes
As variantes servem para testar qual título, tipo de recomendação ou aparência traz mais cliques e compras. As configurações principais do widget são a variante A. Clique em Adicionar variante para criar até três variantes: B, C e D. Em cada uma, você pode alterar:
- o tipo de recomendação, em O que exibir;
- o Título e o Botão, com as traduções;
- o layout e toda a aparência.
Os campos vazios são herdados da variante A.

Os visitantes são divididos igualmente entre as variantes, e cada visitante sempre vê a mesma variante. O seletor acima da pré-visualização mostra a variante escolhida. Os resultados da comparação estão nas estatísticas, abaixo do editor.
Ver no seu site
O botão Ver no seu site, acima da pré-visualização, abre uma página do seu site com o widget como foi salvo. Informe o endereço da página em que o código do widget está inserido, escolha a variante e clique em Abrir.
Assim o widget aparece mesmo desativado ou em uma página fora das regras de exibição. Impressões e cliques nesse modo não entram nas estatísticas. O link vale por 24 horas; enquanto a aba estiver aberta, o modo de visualização continua ao navegar pelas páginas do site. Alterações não salvas não aparecem no site: salve antes.
Código para o site
O código do widget está no card dele na lista e na seção Exibição do editor. Cole-o no modelo da página, no lugar em que o bloco deve aparecer:
<div data-cdp-widget="a1b2c3d4e5f6" data-item="SKU-1"></div>
Atributos:
data-item: id do produto da página ou dos produtos do carrinho, separados por vírgula:data-item="SKU-1,SKU-7". Obrigatório para os tipos “Vistos juntos”, “Comprados juntos” e “Semelhantes”; preencha-o a partir do modelo da página.data-category: id da categoria para produtos populares, se páginas diferentes precisarem de categorias diferentes.data-exclude: ids de produtos, separados por vírgula, que não devem ser exibidos, por exemplo os que já estão no carrinho.
Produtos personalizados e vistos recentemente são escolhidos com base no visitante e não precisam de data-item.
Se não houver produtos adequados, o espaço na página fica vazio, sem quebrar o layout.
Estatísticas
Abaixo do editor ficam as estatísticas do widget de 7, 30 ou 90 dias: totais, gráfico por dia e comparação das variantes. Acima do gráfico, escolha o indicador: impressões, cliques, CTR ou receita. Se o widget tiver variantes, cada uma tem a sua linha no gráfico.

| Indicador | Como é calculado |
|---|---|
| Impressões | o widget entrou no campo de visão do visitante pelo menos pela metade. Carregar a página sem rolar até o bloco não conta, então o CTR de um widget no fim da página é fiel |
| Cliques | cliques nos cards dos produtos |
| CTR | cliques divididos pelas impressões |
| Compras | compras do produto pelo mesmo cliente em até 7 dias após o clique nele; no gráfico, no dia do primeiro clique |
| Receita | o valor dessas compras |
Os dias são contados em UTC. Impressões e cliques da visualização no seu site não são contabilizados.
A tabela de variantes mostra as impressões, os cliques, o CTR, as compras e a receita de cada variante. Abaixo dela há uma conclusão sobre cliques e compras por impressão: qual variante é melhor e se já há dados suficientes para confiar nisso. Enquanto houver poucos dados, a conclusão diz isso: espere, em vez de escolher uma variante por uma diferença casual.
O efeito geral das recomendações no site, por tipo, está na seção Recomendações.
Sites de página única
O rastreador encontra os widgets sozinho depois do carregamento da página, quando surgem novos elementos e quando o data-item muda. Por isso, em sites com React, Vue e similares, basta alterar o atributo, e o bloco é redesenhado.
Se for preciso atualizar os produtos sem mudar os atributos, por exemplo depois de uma alteração no carrinho, chame:
cdp.widgets({ force: true });
Código próprio em vez de widget
Os desenvolvedores podem exibir um bloco de recomendações a partir do código, sem configurar nada no painel administrativo:
window.addEventListener('load', () => {
cdp.renderRecommendations('#recs', {
type: 'viewed_with', item: 'SKU-1', title: 'Vistos juntos', layout: 'carousel', columns: 4,
});
});
O bloco tem a mesma aparência de um widget, e as impressões e os cliques são contabilizados automaticamente. Você pode chamá-lo antes do carregamento do rastreador: a chamada espera na fila. O elemento já precisa estar na página; por isso o exemplo espera o evento load. Um resultado vazio limpa o elemento. A aparência usa as mesmas opções dos widgets do painel administrativo, por exemplo imageRatio: '4:3', imageFit: 'cover', imageBackground: 'transparent', background: '#111827', textColor: '#f9fafb'; imageBackground é uma cor ou transparent. Regras de exibição e variantes estão disponíveis apenas nos widgets do painel administrativo.