groware
/Docs
Instalação

Instalação

2 linhas

Adicione o script no <head> de qualquer página. Substitua tok_xxx pela API key disponível em Configurações → API Keys.

Qualquer sistema HTML
html
<!-- Groware — stub (garante que identify/track funcionam antes do script carregar) -->
<script>
window.Groware=window.Groware||{_q:[],track:function(e,d){this._q.push(["track",e,d])},identify:function(i,t){this._q.push(["identify",i,t])},reset:function(){this._q.push(["reset"])}}
</script>

<!-- Groware — script principal (carrega em paralelo, não bloqueia o HTML) -->
<script async src="https://groware.io/tracker.min.js" data-key="tok_xxx"></script>
Instale antes de qualquer outro script para garantir que UTMs e referrer sejam capturados desde o primeiro carregamento.

Atributos do script

AtributoObrigatórioDescrição / Exemplo
data-keysimAPI key da organização. Obtida em Configurações.tok_convitede_xxx
data-debugnãoHabilita logs no console: "[Groware] track: evento {...}".true
data-auto-abandonnãoDesabilita detecção automática de checkout_abandoned no beforeunload.false

O que é capturado automaticamente

dadofonteexemplo
utm_source?utm_source na URLgoogle
utm_medium?utm_medium na URLcpc
utm_campaign?utm_campaign na URLblack-friday
utm_content?utm_content na URLbanner-topo
landing_pagewindow.location.pathname/convite/casamento
referrerdocument.referrer + inferênciainstagram.com
devicenavigator.userAgentmobile | desktop
session_idsessionStorage (anônimo, gerado)s_abc123

Identificando o usuário (Groware.identify)

Após o login, chame identify() para associar o usuário aos eventos. O tracker enviará automaticamente customer_id, customer_name e customer_email em todos os eventos subsequentes da sessão.

Em projetos Next.js / React, use sempre o hook useTracker — ele é seguro contra SSR e timing de carregamento. Em HTML puro, use o padrão stub abaixo.

HTML puro — após o login do usuário
js
// Após o login do usuário — enriquece o perfil e vincula eventos
window.Groware.identify(user.id, {
  name: user.name,
  email: user.email,
  phone: user.phone,  // opcional
})

// No logout — limpa os dados do perfil da sessão
window.Groware.reset()

// Desse ponto em diante, todos os eventos enviados pelo tracker.js
// incluem automaticamente customer_id, customer_name e customer_email.
Erro .identify is not a function?
O script carrega com async, então window.Groware pode não existir quando você chama identify(). Em HTML puro, use o stub abaixo. Em React/Next.js, use const { identify } = useTracker() — nunca chame window.Groware.identify() diretamente.
HTML puro — stub + script async (padrão correto)
html
<!-- 1. Stub — coloque ANTES do <script async src="...tracker.min.js"> -->
<!-- Garante que identify() funciona mesmo antes do tracker carregar -->
<script>
  window.Groware = window.Groware || { _q: [], track: function(e,d){ this._q.push(['track',e,d]); }, identify: function(id,t){ this._q.push(['identify',id,t]); }, reset: function(){ this._q.push(['reset']); } };
</script>

<!-- 2. Script principal (minificado) — carrega em paralelo sem bloquear o HTML -->
<script async src="https://groware.io/tracker.min.js" data-key="tok_xxx"></script>

<!-- 3. Agora identify() pode ser chamado em qualquer ponto da página -->
<script>
  // Funciona imediatamente (entra na fila se o tracker ainda não carregou)
  window.Groware.identify('user_uuid', { name: 'João', email: 'joao@email.com' })
</script>

Carregamento do script

O Groware oferece dois arquivos de script. O padrão é o tracker.min.js — minificado (~10KB), ideal para produção. O tracker.js (~22KB) é a versão legível, útil apenas para depuração local.

AtributoObrigatórioDescrição / Exemplo
tracker.min.jsrecomendadoVersão minificada (~10KB). Use em produção. Mesmo comportamento do tracker.js.https://groware.io/tracker.min.js
tracker.jsdebugVersão legível (~22KB). Use apenas para inspecionar o código do tracker localmente.https://groware.io/tracker.js

Por que usar async e não defer? O atributo async faz o download do script em paralelo e executa assim que estiver pronto, capturando UTMs e referrer o mais cedo possível. Já o defer atrasa a execução até o HTML terminar de ser analisado, o que pode causar perda de contexto de navegação em SPAs.

Padrão recomendado (async)
html
<!-- Padrão recomendado: stub inline + async (não bloqueia o HTML) -->
<script>
window.Groware=window.Groware||{_q:[],track:function(e,d){this._q.push(["track",e,d])},identify:function(i,t){this._q.push(["identify",i,t])},reset:function(){this._q.push(["reset"])}}
</script>
<script async src="https://groware.io/tracker.min.js" data-key="tok_xxx"></script>

Carregamento lazy (após o page load): Use esta estratégia apenas em sites onde performance é crítica e você não precisa capturar eventos no carregamento inicial.

Lazy loading (após window.load)
html
<script>
window.Groware=window.Groware||{_q:[],track:function(e,d){this._q.push(["track",e,d])},identify:function(i,t){this._q.push(["identify",i,t])},reset:function(){this._q.push(["reset"])}}

window.addEventListener('load', function() {
  var s = document.createElement('script');
  s.src = 'https://groware.io/tracker.min.js';
  s.async = true;
  s.setAttribute('data-key', 'tok_xxx');
  document.head.appendChild(s);
});
</script>
O carregamento lazy garante zero impacto no LCP/FCP, mas pode perder o UTM de origem se o usuário navegar antes do window.load. Para a maioria dos casos, o padrão async é o ideal.
Documentação | Groware