Tracker JavaScript

O NotifyChain Tracker e uma biblioteca JavaScript leve para rastrear eventos no seu site ou aplicacao web.

Caracteristicas

Leve: ~4KB minificado e gzipado
Zero dependencias: Funciona em qualquer ambiente
Offline support: Armazena eventos quando offline
Batching: Agrupa eventos para eficiencia
Retry automatico: Reenvia em caso de falha

Instalacao

Via CDN (Recomendado)

Adicione no <head> do seu site:

<script
  src="https://cdn.notifychain.io/tracker.js"
  data-api-key="SUA_API_KEY"
></script>

O tracker inicializa automaticamente com a API key do atributo.

Via NPM

npm install @notifychain/tracker

import NotifyChain from '@notifychain/tracker';

NotifyChain.init('SUA_API_KEY');

Download Manual

Baixe o arquivo e hospede no seu servidor:

<script src="/js/notifychain-tracker.min.js"></script>
<script>
  NotifyChain.init('SUA_API_KEY');
</script>

Configuracao

Inicializacao Basica

NotifyChain.init('SUA_API_KEY');

Opcoes Avancadas

NotifyChain.init('SUA_API_KEY', {
  // URL do endpoint (padrao: api.notifychain.io)
  endpoint: 'https://api.notifychain.io',

  // Habilitar modo debug
  debug: false,

  // Tamanho do batch (eventos antes de enviar)
  batchSize: 10,

  // Timeout do batch em ms
  batchTimeout: 5000,

  // Maximo de retries em caso de falha
  maxRetries: 3,

  // Habilitar rastreamento automatico de pageviews
  autoPageview: true,

  // Habilitar armazenamento offline
  offlineStorage: true
});

Identificando Usuarios

Identify

Associe eventos a um usuario conhecido:

NotifyChain.identify('user-123', {
  email: 'maria@email.com',
  firstName: 'Maria',
  lastName: 'Silva',
  plan: 'premium',
  createdAt: '2024-01-15'
});

Parametros:

userId: Identificador unico do usuario no seu sistema
traits: Propriedades do usuario (opcional)

Quando Chamar Identify

// Apos login
function onLogin(user) {
  NotifyChain.identify(user.id, {
    email: user.email,
    name: user.name
  });
}

// Apos cadastro
function onSignup(user) {
  NotifyChain.identify(user.id, {
    email: user.email,
    source: 'signup'
  });
  NotifyChain.track('Usuario Cadastrado');
}

// Ao carregar pagina (se ja logado)
if (currentUser) {
  NotifyChain.identify(currentUser.id);
}

Reset

Limpe a identificacao (ex: logout):

NotifyChain.reset();

Rastreando Eventos

Track Basico

NotifyChain.track('Nome do Evento');

Com Propriedades

NotifyChain.track('Compra Realizada', {
  orderId: 'ORD-12345',
  total: 299.90,
  items: [
    { id: 'SKU-001', name: 'Produto A', price: 99.90 }
  ],
  paymentMethod: 'cartao'
});

Exemplos Comuns

Pageview:

NotifyChain.track('Pagina Visitada', {
  path: window.location.pathname,
  title: document.title,
  referrer: document.referrer
});

Clique em Botao:

document.getElementById('cta-button').addEventListener('click', () => {
  NotifyChain.track('Botao Clicado', {
    buttonId: 'cta-button',
    buttonText: 'Comecar Agora',
    page: window.location.pathname
  });
});

Formulario Enviado:

form.addEventListener('submit', () => {
  NotifyChain.track('Formulario Enviado', {
    formId: 'contact-form',
    fields: ['name', 'email', 'message']
  });
});

Video Assistido:

videoPlayer.on('ended', () => {
  NotifyChain.track('Video Assistido', {
    videoId: 'video-123',
    title: 'Tutorial de Onboarding',
    duration: 180,
    percentWatched: 100
  });
});

Rastreamento Automatico

Pageviews

Se autoPageview: true:

// Disparado automaticamente em cada mudanca de pagina
// Inclui: path, title, referrer

Para SPAs (Single Page Applications):

// Chame manualmente em mudancas de rota
router.on('routeChange', (route) => {
  NotifyChain.page({
    path: route.path,
    title: route.title
  });
});

Cliques em Links

Rastreie cliques em links externos:

document.addEventListener('click', (e) => {
  const link = e.target.closest('a');
  if (link && link.hostname !== window.location.hostname) {
    NotifyChain.track('Link Externo Clicado', {
      url: link.href,
      text: link.textContent
    });
  }
});

Modo Debug

Ative para ver eventos no console:

NotifyChain.debug(true);

NotifyChain.track('Teste');
// Console: [NotifyChain] Track: Teste {}
// Console: [NotifyChain] Event queued. Queue size: 1
// Console: [NotifyChain] Batch sent successfully

Armazenamento Offline

Quando o usuario esta offline:

Eventos sao armazenados no localStorage
Ao reconectar, eventos sao enviados automaticamente
Ordem cronologica e mantida

// Verificar eventos pendentes
const pending = NotifyChain.getPendingEvents();
console.log(`${pending.length} eventos aguardando envio`);

Integracao com Frameworks

React

import { useEffect } from 'react';
import NotifyChain from '@notifychain/tracker';

// Hook para rastrear pageviews
function usePageTracking() {
  const location = useLocation();

  useEffect(() => {
    NotifyChain.page({
      path: location.pathname
    });
  }, [location]);
}

// Componente de rastreamento
function TrackButton({ event, properties, children }) {
  const handleClick = () => {
    NotifyChain.track(event, properties);
  };

  return <button onClick={handleClick}>{children}</button>;
}

Vue

// Plugin Vue
export default {
  install(app) {
    app.config.globalProperties.$track = NotifyChain.track;

    app.mixin({
      mounted() {
        if (this.$options.trackPageview !== false) {
          NotifyChain.page();
        }
      }
    });
  }
};

// Uso no componente
this.$track('Botao Clicado', { button: 'comprar' });

Angular

// Service
@Injectable({ providedIn: 'root' })
export class TrackingService {
  track(event: string, properties?: object) {
    NotifyChain.track(event, properties);
  }

  identify(userId: string, traits?: object) {
    NotifyChain.identify(userId, traits);
  }
}

// Componente
constructor(private tracking: TrackingService) {}

onClick() {
  this.tracking.track('Botao Clicado');
}

Seguranca

API Key

Use API keys de producao apenas em producao
API keys sao publicas (visivel no codigo fonte)
Configure dominios permitidos no painel

Dados Sensiveis

Nunca rastreie:

Senhas
Numeros de cartao de credito
Tokens de autenticacao
Dados pessoais sensiveis (CPF, etc.)

// ERRADO - Nunca faca isso!
NotifyChain.track('Login', {
  email: user.email,
  password: user.password  // NUNCA!
});

// CORRETO
NotifyChain.track('Login', {
  method: 'email'
});

Troubleshooting

Eventos nao aparecem

Verifique se a API key esta correta
Ative modo debug e verifique o console
Verifique se o dominio esta permitido
Confira se nao ha bloqueadores (ad blockers)

Erros no Console

"API key not found":

// Certifique-se de inicializar antes de usar
NotifyChain.init('SUA_API_KEY');

"Network error":

// Verifique conexao e URL do endpoint
// Eventos serao reenviados automaticamente

Performance

Se houver impacto na performance:

NotifyChain.init('API_KEY', {
  batchSize: 20,      // Agrupa mais eventos
  batchTimeout: 10000 // Envia menos frequentemente
});

Referencia da API

Metodo	Descricao
`init(apiKey, options)`	Inicializa o tracker
`identify(userId, traits)`	Identifica o usuario
`track(event, properties)`	Rastreia um evento
`page(properties)`	Rastreia pageview
`reset()`	Limpa identificacao
`debug(enabled)`	Ativa/desativa debug
`getPendingEvents()`	Retorna eventos na fila

Caracteristicas​

Instalacao​

Via CDN (Recomendado)​

Via NPM​

Download Manual​

Configuracao​

Inicializacao Basica​

Opcoes Avancadas​

Identificando Usuarios​

Identify​

Quando Chamar Identify​

Reset​

Rastreando Eventos​

Track Basico​

Com Propriedades​

Exemplos Comuns​

Rastreamento Automatico​

Pageviews​

Cliques em Links​

Modo Debug​

Armazenamento Offline​

Integracao com Frameworks​

React​

Vue​

Angular​

Seguranca​

API Key​

Dados Sensiveis​

Troubleshooting​

Eventos nao aparecem​

Erros no Console​

Performance​

Referencia da API​