API JavaScript do loader

O snippet do Data Lead cria um único global: a função DataStone. Ela existe desde a primeira linha da página, antes mesmo de ds.js terminar de carregar, porque o snippet instala um substituto que enfileira as chamadas e as entrega quando o carregador sobe.

<script>
(function(w,d,k,c){w.DataStone=w.DataStone||function(){(w.DataStone.q=w.DataStone.q||[]).push(arguments)};
w.DataStone.k=k;w.DataStone.cdn=c;var s=d.createElement('script');s.async=true;s.src=c+'/v1/ds.js';
(d.head||d.body).appendChild(s)})(window,document,'SITE_KEY','CDN');
</script>

O painel gera esse trecho já com a chave do seu site em Instalação. SITE_KEY é a chave pública do site e CDN é a base dos arquivos do Data Lead.

Comandos

A função aceita um comando por chamada, no formato DataStone(<comando>, …). Hoje existem dois, e nada mais: qualquer outro nome é ignorado em silêncio.

consent — informar o consentimento do visitante

DataStone("consent", "analytics");

Aceita o modo como texto ("essential", "analytics" ou "full") ou o par booleano da API anterior, que é traduzido para o mesmo modo:

DataStone("consent", { analytics: true,  marketing: false }); // "analytics"
DataStone("consent", { analytics: true,  marketing: true  }); // "full"
DataStone("consent", { analytics: false, marketing: false }); // "essential" (revoga)

Detalhes que importam:

• consent é comando do carregador, não do chat. A fila do snippet é drenada por ele antes de qualquer decisão sobre identificador — então chamar consent no <head>, antes de ds.js carregar, funciona.
• Um valor inválido é ignorado: o modo não muda.
• O modo fica em ds_consent_mode, no localStorage do domínio do seu site.
• O modo novo vale a partir do próximo carregamento da página para o coletor de navegação. Não há, hoje, troca de modo ao vivo sem recarregar.

Veja Modos de consentimento para o que cada modo coleta.

lead — abrir e fechar o chat

DataStone("lead", "open");   // abre o painel do chat
DataStone("lead", "close");  // fecha o painel

Use para ligar um botão da sua página ao assistente:

<button type="button" onclick="DataStone('lead','open')">Falar com o assistente</button>

Chamadas feitas antes de o chat montar ficam na fila e são aplicadas assim que ele sobe — o botão funciona mesmo se a pessoa clicar cedo. Abrir o painel também dispara a saudação, uma única vez por conversa.

Propriedades do global

Elas existem para o próprio carregador. Trate-as como somente leitura: escrever nelas não reconfigura nada.

O que não existe (ainda)

Para evitar código que falha em silêncio, vale a lista do que não faz parte da API pública hoje:

• não há comando para enviar mensagem, identificar o visitante, definir atributos, trocar de playbook ou repintar o tema pelo navegador — tema e conteúdo vêm sempre do servidor;
• não há callback nem promessa de "carregado": o chat resolve isso sozinho pela fila;
• window.__DataStoneWidget e window.__DataStoneBehavior são pontos internos entre os bundles do produto. Eles existem no window, mas não são contrato: podem mudar sem aviso. Não os chame.

Navegação em SPA

O coletor (behavior.js) instrumenta history.pushState, history.replaceState, popstate e hashchange. A cada rota nova, ele emite no window um evento próprio, com um atraso de 100 ms para agrupar navegações em rajada. Ele passa a existir quando o coletor carrega — logo depois do load da página, não desde o snippet:

window.addEventListener("datastone:navigate", (e) => {
  console.log("rota nova:", e.detail.url);
});

É esse evento que faz a contagem de páginas e os gatilhos de abordagem funcionarem em aplicações de página única, sem você precisar recarregar o snippet a cada rota. Não reinjete o snippet em transições de rota: uma segunda cópia do carregador não é instalada (os scripts são marcados no DOM), mas o código que faz isso costuma trazer outros efeitos.

O chat não fecha sozinho na troca de rota: a conversa continua de pé enquanto a pessoa navega.

Ordem em que as coisas sobem

1. O snippet cria DataStone e pede ds.js de forma assíncrona.
2. ds.js drena os comandos consent da fila e decide se há identificador de visitante.
3. Em ociosidade (ou no primeiro gesto do visitante — rolagem, mouse, toque ou tecla), ele carrega o chat (widget.js) e o coletor de páginas (behavior.js).
4. O chat pede a configuração ao servidor e desenha o launcher.

Nada disso bloqueia a renderização da sua página. Veja Orçamento e desempenho.

Veja também

• Eventos do dataLayer
• CSP recomendada
• Shadow DOM e estilos
• Modos de consentimento

Precisa de ajuda?

Fale com o suporte da Data Stone pelo canal combinado com a sua conta. Tenha à mão a URL da página e o que aparece no console do navegador.