OneTrace.ru Central de ajuda

Conexão do site

O rastreador é um pequeno script nas páginas do seu site. Ele conta as visualizações de página, envia as ações dos clientes (visualização de produto, carrinho, pedido, login), exibe os widgets de recomendação e inscreve os visitantes no Web Push. Tudo o que é preciso para a conexão está em Engajamento → Site.

A seção fica aberta para todos os membros do projeto. Alterar os domínios do site e os widgets é permitido para “Proprietário”, “Administrador” e “Gerente”. Criar uma chave para o site é permitido para “Proprietário” e “Administrador”.

Instalação do rastreador

A aba Instalação tem três etapas.

1. Código para todas as páginas

  1. No campo Chave de gravação, escolha a chave. Se não houver chaves, clique em Criar uma chave para o site.
  2. Copie o código com o botão de copiar.
  3. Cole-o no <head> de todas as páginas do site, normalmente no modelo comum do cabeçalho.

O código é assim (na seção, o endereço e a chave já vêm preenchidos):

<script>
!function(w,d,u){var c=w.cdp=w.cdp||[];if(c.version)return;['init','page','track','identify','alias','reset','setLanguage','widgets','renderRecommendations'].forEach(function(m){c[m]=c[m]||function(){c.push([m].concat([].slice.call(arguments)))}});var s=d.createElement('script');s.async=1;s.src=u;d.head.appendChild(s)}(window,document,'https://cdp.onetrace.ru/tracker/cdp.js');
cdp.init('cdp_wk_…', { host: 'https://cdp.onetrace.ru' });
cdp.page();
</script>

O script carrega de forma assíncrona e não deixa o site mais lento. As chamadas cdp.track() podem ser feitas logo após o código: elas aguardam o carregamento do rastreador. Para cada navegador, o rastreador gera um identificador de visitante permanente (cookie cdp_aid válido por um ano) e guarda os parâmetros UTM da visita.

A chave de gravação fica visível no código das páginas, e isso é normal: ela só consegue enviar eventos. Se as chaves estiverem indisponíveis na lista, elas foram criadas antes desta seção existir e não podem ser exibidas por completo. Crie uma nova chave para o site ou use a chave do código que já está no site.

Aba “Instalação”: código do rastreador e verificação da instalação

2. Verificação

Depois da instalação, abra qualquer página do site. Em poucos segundos, aparece no bloco Verificação uma tabela com Domínio, Eventos em 7 dias e o horário do último evento. Enquanto não houver eventos, a seção mostra “Aguardando os primeiros eventos”. A verificação se atualiza sozinha a cada 10 segundos enquanto a seção estiver aberta.

3. Domínios do site

Para impedir que outro site envie eventos em nome do seu projeto e obtenha as recomendações, informe os domínios do seu site:

  1. Digite o domínio, por exemplo shop.example.com, e clique em +. Um domínio da tabela de verificação é adicionado pelo botão Adicionar aos domínios.
  2. Clique em Salvar.

O domínio também libera os próprios subdomínios: shop.ru permite www.shop.ru. Enquanto a lista estiver vazia, a chave funciona em qualquer site (“Sem restrição”). A restrição não afeta as requisições do seu servidor. Você pode informar até 20 domínios.

Aplicativos de página única (SPA e PWA)

Em aplicativos com React, Vue, Angular e similares a página não recarrega, então o próprio aplicativo envia as visualizações: chame cdp.page() após cada troca de tela, mas não duas vezes no primeiro carregamento — o código de instalação já enviou. Se o hook do roteador também roda no primeiro carregamento (afterEach no Vue Router, useEffect no React), remova cdp.page() do código de instalação — há um exemplo na aba Instalação.

// após cada troca de tela, quando o roteador já atualizou o endereço
cdp.page();

// uma tela sem endereço próprio, ou o endereço ainda não mudou
cdp.page('Carrinho', { path: '/cart', title: 'Carrinho' });

Se uma tela não tem endereço próprio (um modal, uma etapa do checkout, um PWA sem endereços) ou o roteador muda o endereço depois, passe a página explicitamente: path ou url (pode ser relativa) e o título. Essa página entra na visualização e no contexto dos eventos seguintes — por exemplo, uma adição ao carrinho fica ligada à tela do carrinho — até a próxima chamada de cdp.page(). O rastreador considera a tela anterior como origem da segunda tela em diante e guarda os parâmetros UTM da visita até a aba ser fechada.

Login e logout do cliente

Depois do login ou do cadastro, chame cdp.identify() com o id do usuário no seu sistema, e o histórico de visitas é vinculado ao perfil do cliente:

cdp.identify('user-42', { email: 'anna@example.com' });

Envie o User ID apenas para usuários logados e não use valores genéricos como 0 ou guest: perfis com o mesmo User ID serão mesclados. No logout, chame cdp.reset() para que a próxima pessoa naquele computador receba um novo identificador.

A tabela Identificação do cliente na aba Eventos de produtos mostra quais identificadores cada canal precisa e como eles chegam ao perfil: email para campanhas de email, phone em formato internacional para SMS, WhatsApp e Viber por número e, para os bots do Telegram e do Viber, a vinculação do chat por um link criado pelo seu servidor. Envie tudo o que você sabe sobre o cliente: quanto mais identificadores, mais canais disponíveis.

Idioma do cliente

O rastreador envia o idioma do navegador, que é salvo no perfil do cliente (o atributo language) até que o idioma seja definido explicitamente. Com esse idioma, as jornadas e campanhas escolhem a versão de idioma do modelo. Os idiomas do projeto aparecem no bloco Idioma do cliente da aba Instalação.

Se o site tiver um seletor de idioma, informe a escolha do visitante: ela é lembrada e salva no perfil:

cdp.setLanguage('de');

Outra fonte de idioma é definida na inicialização: language: 'page' — o atributo lang do <html>, um código de idioma — um idioma para o site inteiro, false — não enviar o idioma. Um idioma conhecido no seu sistema pode ser enviado como atributo: cdp.identify('user-42', { language: 'de' }).

Eventos de produtos

A aba Eventos de produtos mostra chamadas prontas para cinco ações: Visualização de produto, Adição ao carrinho, Pedido, Favoritos e Login e cadastro. Os nomes dos eventos e a propriedade com o id do produto (por padrão, product_id) vêm das configurações da seção Recomendações. Se os eventos não estiverem escolhidos lá, você verá um aviso, e os exemplos usarão os nomes padrão: product_viewed, add_to_cart, order_completed.

Exemplo de pedido, com todos os produtos no array products:

cdp.track('order_completed', {
  order_id: 'A-1001',
  amount: 9980,
  products: [{ product_id: 'SKU-1', quantity: 2, price: 4990 }],
});

Favoritos é opcional: os eventos add_to_wishlist e remove_from_wishlist são usados pelas jornadas que avisam sobre queda de preço e reposição de produtos favoritos. Chame cdp.addToWishlist('SKU-1') e cdp.removeFromWishlist('SKU-1') ou dispense o código: adicione ao botão o atributo data-cdp-wishlist="SKU-1" (adicionar) ou data-cdp-wishlist-remove="SKU-1" (remover), e o rastreador envia o evento ao clicar.

Cada etapa tem uma marca: quantos eventos chegaram em 7 dias e quando foi o último, ou “Nenhum evento em 7 dias”. Assim você vê quais chamadas ainda não funcionam. O id do produto deve ser igual ao id no catálogo de produtos.

Aba “Eventos de produtos” com marcas dos eventos recebidos

Pedidos e cadastros são enviados com mais segurança pelo seu servidor; veja Integração pelo servidor.

Links de convite

Se os convites estiverem ativados no programa de fidelidade, cada membro tem um link para o seu site com o parâmetro ?ref=CÓDIGO. O rastreador percebe esse parâmetro sozinho: guarda o código por 30 dias no cookie cdp_ref e envia uma única vez o evento referral_visited. O amigo é contabilizado quando se cadastra ou faz login no site. Os plugins de loja enviam o código do cookie no cadastro; um site próprio, pela API.

Web Push

A aba Web Push mostra se o canal está conectado e quantas inscrições existem. Se não houver canal, crie-o pelo link Abrir integrações, e as chaves aparecem sozinhas (veja Integrações e canais). Depois:

  1. Arquivo do service worker. Crie na raiz do site o arquivo cdp-sw.js com uma única linha: 
    importScripts('https://cdp.onetrace.ru/tracker/cdp-sw.js');
  2. Botão de inscrição. Adicione ao site um botão que, ao ser clicado, chame cdp.push.subscribe(). O navegador só pede permissão para notificações após uma ação do visitante.

As notificações só funcionam em sites com HTTPS. A inscrição é vinculada ao perfil do visitante.

Aba “Web Push”: status do canal e código para o site

CMS e Google Tag Manager

A aba CMS e GTM traz instruções passo a passo para site próprio, Google Tag Manager, 1C-Bitrix, Tilda, WordPress e WooCommerce, InSales: onde colocar o código de instalação, os eventos e os widgets.

Por exemplo, no Google Tag Manager, crie uma tag “HTML personalizado” com o código de instalação e o acionador “Todas as páginas”. Para os eventos de produtos, são necessárias tags separadas com a chamada cdp.track e acionadores pelos eventos do dataLayer (view_item, add_to_cart, purchase). Depois de publicar o contêiner, confira na aba Instalação se os eventos começaram a chegar.

Integração com um agente de IA

Se um desenvolvedor cria o seu site com um agente de IA (Claude Code, Codex, Cursor e outros), entregue ao agente um skill pronto. Na aba Agente de IA, clique em Baixar SKILL.md. O arquivo contém instruções para o agente em inglês com os dados do seu projeto: o endereço do OneTrace.ru, a chave de gravação selecionada, os nomes dos eventos de produtos, os widgets e o status do Web Push. Com elas, o agente adiciona sozinho o código de instalação, os eventos de produtos, o login e o logout, os widgets e a inscrição em notificações.

  1. Se houver várias chaves de gravação, selecione a que você precisa.
  2. Baixe o arquivo e coloque-o no projeto do site: para o Claude Code, em .claude/skills/<nome do skill>/SKILL.md; para outros agentes compatíveis com Agent Skills, na pasta de skills deles, por exemplo .agents/skills/<nome do skill>/SKILL.md. O caminho exato aparece na aba. Você também pode simplesmente anexar o arquivo à sua mensagem para o agente.
  3. Escreva a tarefa para o agente: há um texto de exemplo na aba.

Aba “Agente de IA”: skill com os dados do projeto para um agente de IA

Chaves secretas nunca entram no skill. Se você mudar os eventos nas configurações de recomendações ou adicionar widgets, baixe o skill novamente.

O que é importante saber

  • Robôs de buscadores, prévias de links em mensageiros, serviços de verificação de sites e navegadores automatizados não são contabilizados: o rastreador não envia os eventos deles nem define cookies, mas exibe os widgets de recomendações. Para contabilizar todos os visitantes, adicione a opção ao código de instalação: cdp.init('…', { host: '…', ignoreBots: false }).
  • O rastreador acumula os eventos e os envia em lotes. Se a rede cair, os eventos ficam salvos no navegador e são enviados depois.
  • Todos os eventos do site aparecem em tempo real na seção Eventos.
  • Os widgets de recomendação são configurados na aba Widgets; veja Widgets de recomendação no site.
← Assistentes de IA (MCP) Widgets de recomendação no site →