@azzas/azzas-tracker-web 1.0.82 → 1.0.83

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +130 -130
  2. package/dist/mod.cjs +8 -8
  3. package/dist/mod.cjs.map +1 -1
  4. package/dist/mod.d.cts +0 -0
  5. package/dist/mod.d.ts +0 -0
  6. package/dist/mod.global.js +8 -8
  7. package/dist/mod.global.js.map +1 -1
  8. package/dist/mod.js +8 -8
  9. package/dist/mod.js.map +1 -1
  10. package/dist/mod.vtex.global.js +42 -42
  11. package/package.json +38 -38
package/README.md CHANGED
@@ -1,130 +1,130 @@
1
- # azzas-tracker-web
2
-
3
- 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).
4
-
5
- O objetivo é fornecer uma **camada única e consistente de tracking**, garantindo que todos os eventos sejam tratados, formatados e enviados de forma confiável.
6
-
7
- E, principalmente, centralizar a complexidade e a “inteligência” de tracking **fora dos repositórios das lojas**.
8
-
9
- ---
10
-
11
- ## Fluxo do Tracking
12
-
13
- O pacote segue o seguinte fluxo de eventos:
14
-
15
- 1. **User Action**
16
- Ações do usuário na loja (ex: adicionar ao carrinho, iniciar checkout, finalizar compra).
17
-
18
- 2. **Tracks**
19
- Ponto central que recebe o contexto do evento vindo da ação do usuário e encaminha para o *Formatter*.
20
-
21
- 3. **Formatter**
22
- Acessa a constante `EVENTS` e, baseado no contexto do evento, puxa os parâmetros obrigatórios e entrega a biblioteca de parâmetros (`/params`).
23
-
24
- 4. **Params Library**
25
- Contém **getters** e **resolvers** que garantem que os dados sejam legítimos e que todos os parâmetros sejam corretamente tratados.
26
-
27
- 5. **Adapters**
28
- Módulos responsáveis por enviar os dados formatados para cada destino (Meta, Datalayer, Dito, etc).
29
-
30
- ![FLUXOGRAMA](/public/fluxograma-lib-params.png)
31
-
32
- ## Instalação
33
-
34
-
35
- ```bash
36
- npm install /path/azzas-tracker-web
37
- ```
38
-
39
-
40
- ## Exemplos
41
-
42
- Listagem dos `EVENTS` e função orquestradora `trackWebEvent`:
43
- ```javascript
44
- const EVENTS = {
45
- ADD_PERSONAL_INFO: {
46
- name: 'add_personal_info',
47
- destinations: ['DataLayer'],
48
- requiredParams: ['brand', 'pre_filled', 'currency', 'value', 'subtotal'],
49
- },
50
- VIEW_CART: {
51
- name: 'add_personal_info',
52
- destinations: ['DataLayer', 'Meta', 'Dito'],
53
- requiredParams: ['....'],
54
- }
55
- }
56
-
57
- export async function trackWebEvent(event: EventName, context: EventContext = {}) {
58
- try {
59
- const parameters = await getParameters(context, event);
60
- return await dispatchTrackEvent(event, parameters);
61
- } catch (err) {
62
- return console.error(`[DT] Error tracking event ${event}:`, err);
63
- }
64
- }
65
- ```
66
-
67
- Uso básico da função no consumidor:
68
-
69
-
70
- ```javascript
71
- import { trackWebEvent } from 'azzas-tracker-web';
72
-
73
- // DATA TRACKING | add_personal_info at submit (pre-filled always false)
74
- // @see notion document for more details:
75
- const form: Element = document.querySelector('xxxxxx');
76
- if (form) {
77
- form.addEventListener('submit', () => {
78
- trackWebEvent('ADD_PERSONAL_INFO', { preFilled: false, orderForm: vtexjs.checkout.orderForm });
79
- });
80
- }
81
- ```
82
-
83
- ***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 👍
84
-
85
- ## Teste Local para Ambientes CDN/DENO
86
-
87
- 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.
88
-
89
- Este comando realiza o build mais recente da biblioteca, empacota-o e inicia um servidor HTTP local usando o Deno para servir o arquivo
90
-
91
- 1. Aqui nesse repositório, rode o script que inicia o servidor local:
92
-
93
- ```bash
94
- npm run dev:deno
95
- ```
96
-
97
- O servidor será iniciado e começará a servir o seu arquivo de build no seguinte endereço: http://localhost:4507/.
98
-
99
- 2. No Projeto Consumidor (DENO/FRONT):
100
-
101
- Altere o link do <script> no seu projeto para apontar para o servidor local.
102
-
103
- Você deve usar: <script src="http://localhost:4507/dist/mod.global.js"></script>
104
-
105
-
106
- ## Boas Práticas
107
- - Sempre garantir que os `requiredParams` de cada evento estejam preenchidos antes de enviar.
108
-
109
- - 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.
110
-
111
- - Usar nomes de eventos semânticos e consistentes (ex: VIEW_CART, ADD_PAYMENT_INFO).
112
-
113
- - Manter os contextos enxutos, enviando apenas dados realmente necessários.
114
-
115
- - 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
116
-
117
-
118
- ## Contribuição
119
-
120
- - Adicionar novos eventos em `EVENTS`.
121
-
122
- - 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.
123
-
124
- - Garantir que todos os parâmetros obrigatórios estejam mapeados nos getters/resolvers.
125
-
126
- - Executar build (npm run build) antes de testar no checkout/loja.
127
-
128
- ## Authors
129
-
130
- - Lucas Soares
1
+ # azzas-tracker-web
2
+
3
+ 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).
4
+
5
+ O objetivo é fornecer uma **camada única e consistente de tracking**, garantindo que todos os eventos sejam tratados, formatados e enviados de forma confiável.
6
+
7
+ E, principalmente, centralizar a complexidade e a “inteligência” de tracking **fora dos repositórios das lojas**.
8
+
9
+ ---
10
+
11
+ ## Fluxo do Tracking
12
+
13
+ O pacote segue o seguinte fluxo de eventos:
14
+
15
+ 1. **User Action**
16
+ Ações do usuário na loja (ex: adicionar ao carrinho, iniciar checkout, finalizar compra).
17
+
18
+ 2. **Tracks**
19
+ Ponto central que recebe o contexto do evento vindo da ação do usuário e encaminha para o *Formatter*.
20
+
21
+ 3. **Formatter**
22
+ Acessa a constante `EVENTS` e, baseado no contexto do evento, puxa os parâmetros obrigatórios e entrega a biblioteca de parâmetros (`/params`).
23
+
24
+ 4. **Params Library**
25
+ Contém **getters** e **resolvers** que garantem que os dados sejam legítimos e que todos os parâmetros sejam corretamente tratados.
26
+
27
+ 5. **Adapters**
28
+ Módulos responsáveis por enviar os dados formatados para cada destino (Meta, Datalayer, Dito, etc).
29
+
30
+ ![FLUXOGRAMA](/public/fluxograma-lib-params.png)
31
+
32
+ ## Instalação
33
+
34
+
35
+ ```bash
36
+ npm install /path/azzas-tracker-web
37
+ ```
38
+
39
+
40
+ ## Exemplos
41
+
42
+ Listagem dos `EVENTS` e função orquestradora `trackWebEvent`:
43
+ ```javascript
44
+ const EVENTS = {
45
+ ADD_PERSONAL_INFO: {
46
+ name: 'add_personal_info',
47
+ destinations: ['DataLayer'],
48
+ requiredParams: ['brand', 'pre_filled', 'currency', 'value', 'subtotal'],
49
+ },
50
+ VIEW_CART: {
51
+ name: 'add_personal_info',
52
+ destinations: ['DataLayer', 'Meta', 'Dito'],
53
+ requiredParams: ['....'],
54
+ }
55
+ }
56
+
57
+ export async function trackWebEvent(event: EventName, context: EventContext = {}) {
58
+ try {
59
+ const parameters = await getParameters(context, event);
60
+ return await dispatchTrackEvent(event, parameters);
61
+ } catch (err) {
62
+ return console.error(`[DT] Error tracking event ${event}:`, err);
63
+ }
64
+ }
65
+ ```
66
+
67
+ Uso básico da função no consumidor:
68
+
69
+
70
+ ```javascript
71
+ import { trackWebEvent } from 'azzas-tracker-web';
72
+
73
+ // DATA TRACKING | add_personal_info at submit (pre-filled always false)
74
+ // @see notion document for more details:
75
+ const form: Element = document.querySelector('xxxxxx');
76
+ if (form) {
77
+ form.addEventListener('submit', () => {
78
+ trackWebEvent('ADD_PERSONAL_INFO', { preFilled: false, orderForm: vtexjs.checkout.orderForm });
79
+ });
80
+ }
81
+ ```
82
+
83
+ ***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 👍
84
+
85
+ ## Teste Local para Ambientes CDN/DENO
86
+
87
+ 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.
88
+
89
+ Este comando realiza o build mais recente da biblioteca, empacota-o e inicia um servidor HTTP local usando o Deno para servir o arquivo
90
+
91
+ 1. Aqui nesse repositório, rode o script que inicia o servidor local:
92
+
93
+ ```bash
94
+ npm run dev:deno
95
+ ```
96
+
97
+ O servidor será iniciado e começará a servir o seu arquivo de build no seguinte endereço: http://localhost:4507/.
98
+
99
+ 2. No Projeto Consumidor (DENO/FRONT):
100
+
101
+ Altere o link do <script> no seu projeto para apontar para o servidor local.
102
+
103
+ Você deve usar: <script src="http://localhost:4507/dist/mod.global.js"></script>
104
+
105
+
106
+ ## Boas Práticas
107
+ - Sempre garantir que os `requiredParams` de cada evento estejam preenchidos antes de enviar.
108
+
109
+ - 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.
110
+
111
+ - Usar nomes de eventos semânticos e consistentes (ex: VIEW_CART, ADD_PAYMENT_INFO).
112
+
113
+ - Manter os contextos enxutos, enviando apenas dados realmente necessários.
114
+
115
+ - 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
116
+
117
+
118
+ ## Contribuição
119
+
120
+ - Adicionar novos eventos em `EVENTS`.
121
+
122
+ - 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.
123
+
124
+ - Garantir que todos os parâmetros obrigatórios estejam mapeados nos getters/resolvers.
125
+
126
+ - Executar build (npm run build) antes de testar no checkout/loja.
127
+
128
+ ## Authors
129
+
130
+ - Lucas Soares
package/dist/mod.cjs CHANGED
@@ -607,7 +607,7 @@ async function itemsFromOrderForm(context) {
607
607
  if (!items.length) return [];
608
608
  return await Promise.all(
609
609
  items.map(async (item) => {
610
- var _a2, _b, _c;
610
+ var _a2, _b, _c, _d, _e, _f;
611
611
  return {
612
612
  item_id: item.productId,
613
613
  item_category2: getItemCategory2(item),
@@ -617,11 +617,11 @@ async function itemsFromOrderForm(context) {
617
617
  quantity: item.quantity || 1,
618
618
  item_ref: item.refId || null,
619
619
  item_brand: normalizeBrand((_a2 = item.additionalInfo) == null ? void 0 : _a2.brandName) || ((_b = item.additionalInfo) == null ? void 0 : _b.brandName) || null,
620
- item_sku: await getItemSku(item) || item.id || null,
621
- item_name: item.name.split(" - ").shift() || item.id || null,
620
+ item_sku: await getItemSku(item) || null,
621
+ item_name: (item == null ? void 0 : item.name.replace(item == null ? void 0 : item.skuName, "").trim()) || item.name || null,
622
622
  item_category: getItemCategory(item) || null,
623
- item_variant: item.skuName.split(/[-/]/)[0].trim(),
624
- item_variant2: ((_c = item.skuName.split(/[-/]/).pop()) == null ? void 0 : _c.trim()) || "",
623
+ item_variant: ((_d = (_c = item == null ? void 0 : item.skuName) == null ? void 0 : _c.split(" - ")[0]) == null ? void 0 : _d.trim()) || "",
624
+ item_variant2: ((_f = (_e = item == null ? void 0 : item.skuName) == null ? void 0 : _e.split(" - ")[1]) == null ? void 0 : _f.trim()) || "",
625
625
  item_url: `https://www.farmrio.com.br${item.detailUrl}` || null,
626
626
  discount: getDiscount(item),
627
627
  image_url: resizeVtexImage(item == null ? void 0 : item.image) || resizeVtexImage(item == null ? void 0 : item.imageUrl) || null
@@ -791,7 +791,7 @@ function persistSelectItemOriginFromResolvedItems(items, source) {
791
791
 
792
792
  // src/params/resolvers/items/fromItem.ts
793
793
  async function itemsFromItem(context, event) {
794
- var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
794
+ var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q;
795
795
  const { item, orderForm, itemListName } = context;
796
796
  const resolvedListName = resolveItemListName({ event, item, itemListName });
797
797
  const resolvedItemId = resolveItemId(item);
@@ -810,10 +810,10 @@ async function itemsFromItem(context, event) {
810
810
  item_ref: (item == null ? void 0 : item.ref) || (item == null ? void 0 : item.refId) || (item == null ? void 0 : item.item_ref) || ((_a = item == null ? void 0 : item.additionalProperty) == null ? void 0 : _a.find((i) => i.name === "RefId").value) || ((_c = item == null ? void 0 : item.itemOffered) == null ? void 0 : _c.gtin.substring(0, (_b = item == null ? void 0 : item.itemOffered) == null ? void 0 : _b.gtin.lastIndexOf("_"))) || null,
811
811
  item_brand: ((_d = item == null ? void 0 : item.additionalInfo) == null ? void 0 : _d.brandName) || (item == null ? void 0 : item.item_brand) || ((_e = item == null ? void 0 : item.brand) == null ? void 0 : _e.name) || ((_g = (_f = item == null ? void 0 : item.itemOffered) == null ? void 0 : _f.brand) == null ? void 0 : _g.name) || null,
812
812
  item_sku: (item == null ? void 0 : item.sku) || ((_h = item == null ? void 0 : item.itemOffered) == null ? void 0 : _h.sku) || await getItemSku(item) || null,
813
- item_name: ((_i = item == null ? void 0 : item.name) == null ? void 0 : _i.split(" - ").shift()) || ((_j = item == null ? void 0 : item.item_name) == null ? void 0 : _j.split(" - ").shift()) || ((_m = (_l = (_k = item == null ? void 0 : item.itemOffered) == null ? void 0 : _k.isVariantOf) == null ? void 0 : _l.name) == null ? void 0 : _m.split(" - ").shift()) || null,
813
+ item_name: ((_i = item == null ? void 0 : item.name) == null ? void 0 : _i.replace(item == null ? void 0 : item.skuName, "").trim()) || ((_j = item == null ? void 0 : item.name) == null ? void 0 : _j.split(" - ").shift()) || ((_k = item == null ? void 0 : item.item_name) == null ? void 0 : _k.split(" - ").shift()) || ((_n = (_m = (_l = item == null ? void 0 : item.itemOffered) == null ? void 0 : _l.isVariantOf) == null ? void 0 : _m.name) == null ? void 0 : _n.split(" - ").shift()) || null,
814
814
  item_category: getItemCategory(item) || null,
815
815
  item_variant: ((item == null ? void 0 : item.skuName) || (item == null ? void 0 : item.item_variant) || (item == null ? void 0 : item.name) || (item == null ? void 0 : item.itemOffered.name)).split(/[-/]/)[0].trim() || null,
816
- item_variant2: (item == null ? void 0 : item.size) || ((_n = item == null ? void 0 : item.itemAttributes) == null ? void 0 : _n.size) || ((_p = (_o = (item == null ? void 0 : item.skuName) || (item == null ? void 0 : item.name) || (item == null ? void 0 : item.itemOffered.name)) == null ? void 0 : _o.split(/[-/]/).pop()) == null ? void 0 : _p.trim()) || null,
816
+ item_variant2: (item == null ? void 0 : item.size) || ((_o = item == null ? void 0 : item.itemAttributes) == null ? void 0 : _o.size) || ((_q = (_p = (item == null ? void 0 : item.skuName) || (item == null ? void 0 : item.name) || (item == null ? void 0 : item.itemOffered.name)) == null ? void 0 : _p.split(/[-/]/).pop()) == null ? void 0 : _q.trim()) || null,
817
817
  discount: getDiscount(item),
818
818
  item_list_name: resolvedListName,
819
819
  item_url: (item == null ? void 0 : item.item_url) || null,