# 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).  

![FLUXOGRAMA](/public/fluxograma-lib-params.png)

## Instalação


```bash
npm install /path/azzas-tracker-web
```


## Exemplos

Listagem dos `EVENTS` e função orquestradora `trackWebEvent`:
```javascript
  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:


```javascript
  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 (<script src="...">), 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:

```bash
  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 <script> no seu projeto para apontar para o servidor local.

Você deve usar: <script src="http://localhost:4507/dist/mod.global.js"></script>


## 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