@azzas/azzas-tracker-web 1.0.81 → 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 +37 -21
  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 +37 -21
  7. package/dist/mod.global.js.map +1 -1
  8. package/dist/mod.js +37 -21
  9. package/dist/mod.js.map +1 -1
  10. package/dist/mod.vtex.global.js +71 -55
  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
@@ -658,7 +658,22 @@ function isFreshTimestamp(timestamp) {
658
658
  function isStoredItemMemory(value) {
659
659
  if (!value || typeof value !== "object") return false;
660
660
  const candidate = value;
661
- return typeof candidate.id === "string" && typeof candidate.list === "string" && typeof candidate.timestamp === "number";
661
+ return typeof candidate.item_id === "string" && typeof candidate.item_list_name === "string" && typeof candidate.timestamp === "number";
662
+ }
663
+ function normalizeStoredItemMemory(value) {
664
+ if (!value || typeof value !== "object") return null;
665
+ const candidate = value;
666
+ const itemId = candidate.item_id;
667
+ const itemListName = candidate.item_list_name;
668
+ const timestamp = candidate.timestamp;
669
+ if (typeof itemId !== "string" || typeof itemListName !== "string" || typeof timestamp !== "number") {
670
+ return null;
671
+ }
672
+ return {
673
+ item_id: itemId,
674
+ item_list_name: itemListName,
675
+ timestamp
676
+ };
662
677
  }
663
678
  function resolveIdFromUnknownItem(item) {
664
679
  var _a, _b, _c, _d, _e;
@@ -673,7 +688,8 @@ function readStoredItem(key) {
673
688
  if (!storage) return null;
674
689
  try {
675
690
  const parsed = parseJSON(storage.getItem(key));
676
- return isStoredItemMemory(parsed) ? parsed : null;
691
+ const normalized = normalizeStoredItemMemory(parsed);
692
+ return normalized && isStoredItemMemory(normalized) ? normalized : null;
677
693
  } catch (e) {
678
694
  return null;
679
695
  }
@@ -692,7 +708,7 @@ function readCartHistory() {
692
708
  try {
693
709
  const parsed = parseJSON(storage.getItem(CART_LIST_HISTORY_KEY));
694
710
  if (!Array.isArray(parsed)) return [];
695
- return parsed.filter((entry) => !!entry && typeof entry === "object" && typeof entry.id === "string" && typeof entry.list === "string");
711
+ return parsed.filter((entry) => !!entry && typeof entry === "object" && typeof entry.item_id === "string" && typeof entry.item_list_name === "string");
696
712
  } catch (e) {
697
713
  return [];
698
714
  }
@@ -708,8 +724,8 @@ function writeCartHistory(history) {
708
724
  function saveSelectedItem(productId, listName) {
709
725
  if (productId == null || !listName) return;
710
726
  const payload = {
711
- id: String(productId),
712
- list: String(listName),
727
+ item_id: String(productId),
728
+ item_list_name: String(listName),
713
729
  timestamp: Date.now()
714
730
  };
715
731
  writeStoredItem(LAST_SELECTED_ITEM_KEY, payload);
@@ -717,8 +733,8 @@ function saveSelectedItem(productId, listName) {
717
733
  function saveViewedItem(productId, listName) {
718
734
  if (productId == null) return;
719
735
  const payload = {
720
- id: String(productId),
721
- list: String(listName != null ? listName : "PDP"),
736
+ item_id: String(productId),
737
+ item_list_name: String(listName != null ? listName : "PDP"),
722
738
  timestamp: Date.now()
723
739
  };
724
740
  writeStoredItem(STORAGE_VIEWED, payload);
@@ -733,16 +749,16 @@ function resolveItemListName(params) {
733
749
  if (!currentItemId) return "PDP";
734
750
  const selectedItem = readStoredItem(LAST_SELECTED_ITEM_KEY);
735
751
  if (!selectedItem) return "PDP";
736
- if (selectedItem.id === currentItemId && isFreshTimestamp(selectedItem.timestamp)) {
737
- return selectedItem.list;
752
+ if (selectedItem.item_id === currentItemId && isFreshTimestamp(selectedItem.timestamp)) {
753
+ return selectedItem.item_list_name;
738
754
  }
739
755
  return "PDP";
740
756
  }
741
757
  if (currentListName !== "PDP" && currentListName !== null) return currentListName;
742
758
  if (!currentItemId) return currentListName;
743
759
  const viewedItem = readStoredItem(STORAGE_VIEWED);
744
- if (viewedItem && viewedItem.id === currentItemId && isFreshTimestamp(viewedItem.timestamp)) {
745
- return viewedItem.list;
760
+ if (viewedItem && viewedItem.item_id === currentItemId && isFreshTimestamp(viewedItem.timestamp)) {
761
+ return viewedItem.item_list_name;
746
762
  }
747
763
  return currentListName === "PDP" ? "PDP" : null;
748
764
  }
@@ -750,8 +766,8 @@ function appendCartHistory(productId, listName) {
750
766
  if (productId == null) return;
751
767
  const history = readCartHistory();
752
768
  history.push({
753
- id: String(productId),
754
- list: listName ? String(listName) : "PDP"
769
+ item_id: String(productId),
770
+ item_list_name: listName ? String(listName) : "PDP"
755
771
  });
756
772
  writeCartHistory(history);
757
773
  }
@@ -775,7 +791,7 @@ function persistSelectItemOriginFromResolvedItems(items, source) {
775
791
 
776
792
  // src/params/resolvers/items/fromItem.ts
777
793
  async function itemsFromItem(context, event) {
778
- 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;
779
795
  const { item, orderForm, itemListName } = context;
780
796
  const resolvedListName = resolveItemListName({ event, item, itemListName });
781
797
  const resolvedItemId = resolveItemId(item);
@@ -794,10 +810,10 @@ async function itemsFromItem(context, event) {
794
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,
795
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,
796
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,
797
- 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,
798
814
  item_category: getItemCategory(item) || null,
799
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,
800
- 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,
801
817
  discount: getDiscount(item),
802
818
  item_list_name: resolvedListName,
803
819
  item_url: (item == null ? void 0 : item.item_url) || null,