azzas-tracker-web

Pacote interno para Data Tracking das lojas WEB, centralizando a captura e envio de eventos para diferentes plataformas de mídia (Meta, Dito, DataLayer, etc).

O objetivo é fornecer uma camada única e consistente de tracking, garantindo que todos os eventos sejam tratados, formatados e enviados de forma confiável.

E, principalmente, centralizar a complexidade e a “inteligência” de tracking fora dos repositórios das lojas.

Fluxo do Tracking

O pacote segue o seguinte fluxo de eventos:

1. User Action
   Ações do usuário na loja (ex: adicionar ao carrinho, iniciar checkout, finalizar compra).

2. Tracks
   Ponto central que recebe o contexto do evento vindo da ação do usuário e encaminha para o Formatter.

3. Formatter
   Acessa a constante EVENTS e, baseado no contexto do evento, puxa os parâmetros obrigatórios e entrega a biblioteca de parâmetros (/params).

4. Params Library
   Contém getters e resolvers que garantem que os dados sejam legítimos e que todos os parâmetros sejam corretamente tratados.

5. Adapters
   Módulos responsáveis por enviar os dados formatados para cada destino (Meta, Datalayer, Dito, etc).

Instalação

npm install /path/azzas-tracker-web

Exemplos

Listagem dos EVENTS e função orquestradora trackWebEvent:

  const EVENTS = {
    ADD_PERSONAL_INFO: {
      name: 'add_personal_info',
      destinations: ['DataLayer'],
      requiredParams: ['brand', 'pre_filled', 'currency', 'value', 'subtotal'],
    }, 
    VIEW_CART: {
      name: 'add_personal_info',
      destinations: ['DataLayer', 'Meta', 'Dito'],
      requiredParams: ['....'],
    }
  }

  export async function trackWebEvent(event: EventName, context: EventContext = {}) {
    try {
      const parameters = await getParameters(context, event);
      return await dispatchTrackEvent(event, parameters);
    } catch (err) {
      return console.error(`[DT] Error tracking event ${event}:`, err);
    }
  }

Uso básico da função no consumidor:

  import { trackWebEvent } from 'azzas-tracker-web';

  // DATA TRACKING | add_personal_info at submit (pre-filled always false)
  // @see notion document for more details:
  const form: Element = document.querySelector('xxxxxx');
  if (form) {
    form.addEventListener('submit', () => {
      trackWebEvent('ADD_PERSONAL_INFO', { preFilled: false, orderForm: vtexjs.checkout.orderForm });
    });
  }

OBS: atente-se ao adicionar eventos novos e contribua na documentação do NOTION ou apenas DOCUMENTE em algum lugar! Seu futuro EU será grato 👍

Teste Local para Ambientes CDN/DENO

Para testar alterações na biblioteca localmente, simulando a forma como ela é carregada por uma CDN (), use o script npm run dev:deno.

Este comando realiza o build mais recente da biblioteca, empacota-o e inicia um servidor HTTP local usando o Deno para servir o arquivo

1. Aqui nesse repositório, rode o script que inicia o servidor local:

  npm run dev:deno

O servidor será iniciado e começará a servir o seu arquivo de build no seguinte endereço: http://localhost:4507/.

2. No Projeto Consumidor (DENO/FRONT):

Altere o link do no seu projeto para apontar para o servidor local.

Você deve usar:

Boas Práticas

• Sempre garantir que os requiredParams de cada evento estejam preenchidos antes de enviar.

• Procure sempre manter o envio das ações de usuário o mais genérico possível. Toda a inteligência e complexidade do tratamento dos dados deve ficar centralizada na lib, e não nos repositórios das lojas.

• Usar nomes de eventos semânticos e consistentes (ex: VIEW_CART, ADD_PAYMENT_INFO).

• Manter os contextos enxutos, enviando apenas dados realmente necessários.

• Cada novo evento deve ser registrado em EVENTS com seus destinos e parâmetros obrigatórios. Essa constante talvez venha a ser dinâmica dependendo da MARCA utilizada

Contribuição

• Adicionar novos eventos em EVENTS.

• Criar adapter correspondente caso seja necessário integrar com nova plataforma. Nesse caso deve-se avaliar qual será o serviço feito, o que será consumido, para onde será enviado.

• Garantir que todos os parâmetros obrigatórios estejam mapeados nos getters/resolvers.

• Executar build (npm run build) antes de testar no checkout/loja.

Authors

• Lucas Soares