mkfashion-sdk 2.7.2 → 2.7.3

package/docs/2026-05-22-sdk-v3-ecommerce-tracking-design.md

@@ -0,0 +1,311 @@
+# SDK v3 — Tracking de E-commerce Completo (Core Tracker) — Design Spec
+
+**Empresa:** MetaKosmos
+**Data:** 2026-05-22
+**Status:** Rascunho para revisão
+**Repos afetados:** `mkfashion-sdk`, `mk-collector-api`
+
+---
+
+## 1. Contexto e motivação
+
+### Situação atual (v2.7.2)
+
+A `mkfashion-sdk` roda **apenas na PDP** (página de produto). O cliente chama
+`mkfashion.init({ projectId, identifier })` ou `isAvailable(...)` na PDP, e a
+partir daí a SDK:
+
+- Auto-captura `page_view`, `page_click`, `page_scroll_depth`, `page_form_submit`,
+  `page_engagement` da PDP.
+- Captura eventos do iframe de try-on (`page_modal_opened`, `page_generation_complete`, etc).
+- Detecta `add_to_cart` por heurística de texto de botão.
+
+**Limitação:** só enxergamos a PDP. Não vemos a jornada completa do visitante —
+entrada, navegação por categorias, carrinho, checkout e **compra final**. Sem o
+purchase, não conseguimos responder a pergunta de negócio mais importante:
+
+> **"Visitantes que usaram o try-on convertem mais do que os que não usaram?"**
+
+### Objetivo da v3
+
+Transformar a SDK de "widget de PDP" em **core tracker de e-commerce** que roda
+em **todas as páginas** do site, capturando o funil completo:
+
+```
+entrada → navegação → produto → (try-on) → carrinho → checkout → COMPRA
+```
+
+**Restrições de design (decididas com o stakeholder):**
+
+1. **Zero trabalho extra pro cliente** além de importar o script. Nada de chamar
+   métodos novos, nada de configurar dataLayer.
+2. **Zero dependência de ferramentas de terceiros** (GA4/GTM podem não existir
+   na loja). Captura por sinais NATIVOS do e-commerce.
+3. **Try-on continua igual**: a marca chama `open()`/`isAvailable()` só na PDP,
+   exatamente como hoje.
+4. **Compatibilidade**: clientes na v2 (SDK na PDP) continuam funcionando durante
+   a migração.
+
+---
+
+## 2. Princípio central: captura por sinais nativos
+
+Toda loja — independente de ter GA4, GTM, ou qualquer analytics — possui 3 coisas
+que existem porque a loja precisa **funcionar e ser indexada**:
+
+| Sinal nativo | Sempre existe? | Usado para |
+|---|---|---|
+| **URLs estruturadas** | ✅ sim | detectar etapa do funil (pdp/cart/checkout/purchase) |
+| **Botões/links clicáveis** | ✅ sim | add_to_cart, begin_checkout (heurística de texto) |
+| **HTML semântico** (JSON-LD, meta, DOM) | ✅ quase sempre | produto, preço, order_id, revenue |
+
+**Hierarquia de confiança para cada dado:**
+
+```
+Conversão (houve compra?)     → URL de confirmação        → 100% confiável
+Produto visto                 → URL /produto + JSON-LD     → 100%
+Add to cart                   → clique em botão (heur.)    → ~90%
+Revenue da compra             → JSON-LD Order > DOM > meta → best-effort
+```
+
+> **dataLayer é tratado como BÔNUS oportunístico** — se existir, enriquece; se
+> não, ignoramos. Nunca é dependência.
+
+### A distinção crucial: conversão vs revenue
+
+- **Conversão (binária)**: "houve uma compra?" → detectável 100% por URL da
+  página de confirmação. Já responde a pergunta de negócio principal.
+- **Revenue (valor exato)**: best-effort via JSON-LD/DOM. Se a loja não expõe,
+  fica sem valor — mas a conversão continua contada.
+
+---
+
+## 3. Arquitetura em camadas
+
+```
+mkfashion-sdk (v3)
+│
+├── core/                          ← roda em TODA página
+│   ├── identity.js     visitorId + sessionId (localStorage/sessionStorage)
+│   ├── transport.js    batch + flush + sendBeacon
+│   ├── pageContext.js  detecta tipo de página por URL/JSON-LD
+│   ├── autoTrack.js    page_view, click, scroll, form, engagement
+│   └── sanitize.js     remove PII e campos pesados antes de enviar
+│
+├── ecommerce/                     ← NOVO — funil de compra (sinais nativos)
+│   ├── catalog.js      view_item_list, select_item, view_item (URL + JSON-LD)
+│   ├── cart.js         add_to_cart (heurística), view_cart (URL)
+│   ├── checkout.js     begin_checkout (URL/clique), purchase (URL + extração)
+│   └── extractors.js   JSON-LD, meta tags, DOM scraping, dataLayer (bônus)
+│
+└── tryon/                         ← módulo existente (sem mudança funcional)
+    └── open(), isAvailable(), getAvailability(), postMessage bridge
+```
+
+### Carregamento
+
+```html
+<!-- Cliente coloca no <head> do TEMA GLOBAL (todas as páginas) -->
+<script src="https://unpkg.com/mkfashion-sdk@3/src/mkfashion.js"
+        data-mk-project="698c7c681d3129430f15dddb"
+        async></script>
+```
+
+Single source: a SDK detecta a página, inicia o tracking de core + ecommerce, e
+expõe a API de try-on pra ser chamada na PDP.
+
+---
+
+## 4. Detecção de contexto de página
+
+`core/pageContext.js` classifica a página em cascata (primeiro match vence):
+
+```js
+function detectPageType() {
+  // 1. Override explícito (se o cliente quiser forçar)
+  if (window.__mkPageType) return window.__mkPageType
+
+  // 2. JSON-LD (@type indica tipo de página)
+  const ld = readJsonLd()
+  if (ld?.['@type'] === 'Product') return 'pdp'
+  if (ld?.['@type'] === 'Order' || ld?.['@type'] === 'Invoice') return 'purchase'
+  if (ld?.['@type'] === 'CollectionPage' || ld?.['@type'] === 'SearchResultsPage') return 'category'
+
+  // 3. URL patterns (fallback universal)
+  const p = location.pathname.toLowerCase()
+  if (p === '/' || p === '') return 'home'
+  if (/\/(thank[_-]?you|orders?\/|pedido[_-]?(confirmado|realizado)|sucesso|order[_-]confirmation)/.test(p)) return 'purchase'
+  if (/\/checkout/.test(p)) return 'checkout'
+  if (/\/(cart|carrinho|sacola|bag)(\/|$|\?)/.test(p)) return 'cart'
+  if (/\/(products?|produtos?|p)\//.test(p)) return 'pdp'
+  if (/\/(collections?|categoria|c)\//.test(p)) return 'category'
+  if (/\/(search|busca|s)(\/|\?)/.test(p)) return 'search'
+  return 'other'
+}
+```
+
+Cada `page_view` carrega `pageType` no `params`, dando semântica ao funil.
+
+---
+
+## 5. Mapa de eventos do funil
+
+| Etapa | Evento (collector) | Como detecta (sem GA) | Dados |
+|---|---|---|---|
+| Entrada | `page_view` + pageType | sempre | url, referrer, utm, pageType |
+| Listagem | `page_view_item_list` | pageType=category + JSON-LD ItemList | SKUs visíveis |
+| Seleção | `page_select_item` | clique em card de produto (link `/produto/`) | SKU clicado |
+| Produto | `page_view_item` | pageType=pdp + JSON-LD Product | SKU, preço, nome |
+| Try-on | `page_modal_opened`, `page_generation_complete`, ... | já existe (postMessage) | já existe |
+| Add cart | `page_add_to_cart` | heurística de clique (já temos) + JSON-LD price | SKU, texto botão |
+| Carrinho | `page_view_cart` | pageType=cart | — |
+| Checkout | `page_begin_checkout` | pageType=checkout OU clique "Finalizar" | — |
+| **Compra** | `page_purchase` | **pageType=purchase (URL)** | orderId?, revenue?, items? |
+
+---
+
+## 6. Detecção de purchase (o ponto crítico)
+
+### 6.1 Conversão (binária) — 100% confiável
+
+Ao detectar `pageType === 'purchase'` (via URL/JSON-LD), emite `page_purchase`
+imediatamente. Isso conta a conversão mesmo sem revenue.
+
+### 6.2 Revenue (best-effort) — cascata de extractors
+
+```js
+function extractOrderData() {
+  // 1. JSON-LD Order (existe pro SEO, independente de GA)
+  const ld = readJsonLd(['Order', 'Invoice'])
+  if (ld) return { orderId: ld.orderNumber || ld.confirmationNumber,
+                   revenue: ld.price || ld.totalPaymentDue?.price,
+                   currency: ld.priceCurrency }
+
+  // 2. dataLayer (BÔNUS — só se a loja tiver GA/GTM)
+  const dl = window.dataLayer?.find(x => x.event === 'purchase' && x.ecommerce)
+  if (dl) return { orderId: dl.ecommerce.transaction_id,
+                   revenue: dl.ecommerce.value,
+                   currency: dl.ecommerce.currency,
+                   items: dl.ecommerce.items }
+
+  // 3. Meta tags
+  const metaTotal = document.querySelector('meta[property="order:total"]')?.content
+  if (metaTotal) return { revenue: parseFloat(metaTotal) }
+
+  // 4. DOM scraping (fallback frágil — best-effort)
+  //    procura elementos com classe/texto de total: .order-total, #total, "Total: R$"
+  const domTotal = scrapeOrderTotal()
+  if (domTotal) return { revenue: domTotal, _source: 'dom_scrape' }
+
+  return null  // conversão já contada; sem revenue
+}
+```
+
+### 6.3 Dedup
+
+Página de confirmação pode recarregar (F5) → mesma compra contada 2x. Dedup por:
+- `orderId` quando disponível (collector ignora purchase com orderId já visto)
+- fallback: 1 purchase por `sessionId` por janela de 1h
+
+### 6.4 Opt-in pra precisão (opcional, não obrigatório)
+
+Cliente que QUER revenue garantido e não tem JSON-LD pode chamar 1 linha:
+```js
+mkfashion.trackPurchase({ orderId: 'X', revenue: 599.80, currency: 'BRL' })
+```
+Mas é **opcional** — a captura automática cobre a maioria.
+
+---
+
+## 7. A pergunta de negócio que isso destrava
+
+Com `visitorId` consistente em todas as páginas + purchase capturado:
+
+```
+Coorte A: visitantes que abriram try-on (page_modal_opened)
+Coorte B: visitantes que NÃO abriram
+
+Conversão A = purchases(A) / visitantes(A)
+Conversão B = purchases(B) / visitantes(B)
+
+Uplift = Conversão A / Conversão B
+```
+
+Exemplo de resultado esperado:
+```
+Try-on:    8.2% convertem
+Sem try-on: 3.1% convertem
+Uplift:    2.6x  ← argumento de venda do produto MK
+```
+
+---
+
+## 8. Fases de implementação
+
+| Fase | Escopo | Risco |
+|---|---|---|
+| **1** | Refatorar SDK em `core/ ecommerce/ tryon/` sem mudar comportamento | baixo |
+| **2** | `pageContext.js` — detecção de tipo de página | baixo |
+| **3** | `extractors.js` — JSON-LD, meta, DOM, dataLayer(bônus) | médio |
+| **4** | `ecommerce/*` — eventos de funil (view_item, cart, checkout, purchase) | médio |
+| **5** | Backend: novos event types + dedup de purchase + agregação de funil | médio |
+| **6** | Cliente migra snippet pra tema global | baixo (config) |
+| **7** | Dashboard de funil + atribuição try-on→conversão | médio |
+
+---
+
+## 9. Mudanças no backend (mk-collector-api)
+
+- Novos `event_name` aceitos (validação já é livre — `page_*`).
+- `sdk-aggregator.service.js`: agregar funil por dia:
+  ```js
+  funnel: {
+    sessions, viewItem, addToCart, beginCheckout, purchase,
+    purchaseRevenue, conversionRate
+  }
+  ```
+- Dedup de purchase por `orderId` (nova lógica no controller ou aggregator).
+- `sdk_daily_metrics`: campos novos `purchases`, `revenue`, `funnel`.
+- Atribuição try-on: cruzar visitors com `page_modal_opened` × `page_purchase`
+  (no aggregator ou query sob demanda).
+
+---
+
+## 10. Privacidade / LGPD
+
+- **NUNCA** capturar campos de formulário de checkout (email, CPF, endereço, cartão).
+- `core/sanitize.js` filtra chaves sensíveis (`email`, `cpf`, `phone`, `address`,
+  `card`, `password`) de qualquer payload antes de enviar.
+- `orderId` e `revenue` não são PII.
+- IP continua sendo descartado server-side (só GeoIP).
+
+---
+
+## 11. Riscos e mitigações
+
+| Risco | Mitigação |
+|---|---|
+| Loja sem JSON-LD nem dataLayer | Conversão por URL (100%); revenue fica nulo (aceitável) |
+| URL de confirmação atípica | Lista de patterns extensível + override `window.__mkPageType` |
+| Purchase contado 2x (refresh) | Dedup por orderId / sessionId |
+| DOM scraping frágil | Marcado com `_source: 'dom_scrape'` pra saber confiabilidade |
+| Volume 5-10x maior (todas páginas) | Batching + sampling de eventos de baixo valor |
+| PII vazando | sanitize.js + nunca ler campos de form |
+| SPA sem reload entre páginas | history.pushState hook (já temos) re-detecta pageType |
+
+---
+
+## 12. Decisões em aberto (pra próxima revisão)
+
+1. Nome do pacote: manter `mkfashion-sdk` v3 ou renomear? (decidir depois)
+2. Sampling: amostrar `page_scroll_depth`/`page_engagement` em sites de alto volume?
+3. Atribuição try-on→conversão: pré-computar no aggregator ou query sob demanda?
+4. Dashboard de funil: nova aba ou endpoint `/api/export/funnel`?
+
+---
+
+## 13. Referências
+
+- SDK atual: `mkfashion-sdk/src/mkfashion.js` (v2.7.2)
+- Collector: `mk-collector-api/` (rotas `/v1/track/sdk`, agregadores)
+- Spec de eventos GA4 ecommerce (usado só como referência de naming dos eventos)

package/index.html

@@ -1,178 +1,79 @@
-<!DOCTYPE html>
-<html lang="pt-BR">
-
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Provador Virtual</title>
-  <script src="./src/mkfashion.js"></script>
-</head>
-
-<body>
-
-  <div id="mkfashion-container"></div>
-
-  <script>
-    (function () {
-      var projectid = '69f9e5b0f4eb0c4403319830';
-
-      // ============================================================
-      // Detecta o identifier (SKU) da PDP automaticamente.
-      // Estratégias em ordem de prioridade — retorna a primeira que casar.
-      // ============================================================
-      function detectIdentifier() {
-        // 1. Query string (?sku=... ou ?identifier=...) — útil pra teste / override
-        var qs = new URLSearchParams(location.search);
-        var fromUrl = qs.get('sku') || qs.get('identifier');
-        if (fromUrl) return { value: fromUrl, source: 'url-param' };
-
-        // 2. JSON-LD (Schema.org Product) — presente em PDPs com SEO decente
-        var scripts = document.querySelectorAll('script[type="application/ld+json"]');
-        for (var i = 0; i < scripts.length; i++) {
-          try {
-            var data = JSON.parse(scripts[i].textContent);
-            var items = Array.isArray(data) ? data : [data];
-            for (var j = 0; j < items.length; j++) {
-              var node = items[j];
-              var product = node['@type'] === 'Product' ? node :
-                (node['@graph'] && node['@graph'].find(function (g) { return g['@type'] === 'Product'; }));
-              if (product) {
-                var sku = product.sku || product.mpn || product.productID;
-                if (sku) return { value: String(sku), source: 'json-ld' };
-              }
-            }
-          } catch (e) { /* json inválido — ignora */ }
-        }
-
-        // 3. Meta tags
-        var meta = document.querySelector(
-          'meta[itemprop="sku"], meta[property="product:retailer_item_id"], meta[name="sku"]'
-        );
-        if (meta && meta.content) return { value: meta.content, source: 'meta' };
-
-        // 4. Microdata em qualquer elemento
-        var micro = document.querySelector('[itemprop="sku"]');
-        if (micro) {
-          var v = micro.getAttribute('content') || (micro.textContent || '').trim();
-          if (v) return { value: v, source: 'microdata' };
-        }
-
-        // 5. dataLayer (GA4 / Enhanced Ecommerce)
-        if (window.dataLayer && window.dataLayer.length) {
-          for (var k = window.dataLayer.length - 1; k >= 0; k--) {
-            var e = window.dataLayer[k] || {};
-            // GA4
-            if (e.ecommerce && e.ecommerce.items && e.ecommerce.items[0]) {
-              var ga4 = e.ecommerce.items[0].item_id || e.ecommerce.items[0].id;
-              if (ga4) return { value: String(ga4), source: 'dataLayer/ga4' };
-            }
-            // Universal Analytics Enhanced Ecommerce
-            if (e.ecommerce && e.ecommerce.detail && e.ecommerce.detail.products && e.ecommerce.detail.products[0]) {
-              var ee = e.ecommerce.detail.products[0].id;
-              if (ee) return { value: String(ee), source: 'dataLayer/ee' };
-            }
-          }
-        }
-
-        // 6. Globais de plataforma
-        if (window.ShopifyAnalytics && window.ShopifyAnalytics.meta && window.ShopifyAnalytics.meta.product) {
-          return { value: String(window.ShopifyAnalytics.meta.product.id), source: 'shopify' };
-        }
-        // VTEX — várias formas de expor a SKU
-        if (window.vtxctx && window.vtxctx.skus && window.vtxctx.skus[0]) {
-          return { value: String(window.vtxctx.skus[0]), source: 'vtex/vtxctx' };
-        }
-        if (window.skuJson_0 && window.skuJson_0.skus && window.skuJson_0.skus[0]) {
-          return { value: String(window.skuJson_0.skus[0].sku), source: 'vtex/skuJson' };
-        }
-        // Konfidency (serviço de reviews usado por várias marcas BR — Marisa, etc.)
-        var kd = window.konfidencyData;
-        if (kd && kd.product && kd.product.variants && kd.product.variants[0]) {
-          return { value: String(kd.product.variants[0]), source: 'konfidency/variant' };
-        }
-
-        // Nota: NÃO usamos padrão de URL como fallback (ex: /p/{id} na VTEX
-        // retorna o productId, não o SKU). É melhor falhar do que dar dado
-        // errado — quem precisar de override deve passar ?sku= na URL.
-
-        // 7. Fallback hardcoded — útil pra rodar index.html localmente sem
-        // estrutura de PDP. Em produção, remova ou ajuste pro seu cenário.
-        return { value: '1881', source: 'fallback-hardcoded' };
-      }
-
-      // ============================================================
-      // Inicialização
-      // ============================================================
-      function initMkFashion() {
-        var detected = detectIdentifier();
-        console.log('[mKFashion] SKU detectado:', detected.value, '(via ' + detected.source + ')');
-
-        // Callback de carrinho — recebe o produto escolhido no provador
-        // e adiciona ao carrinho da plataforma (exemplo: Shopify).
-        mkfashion.addToCart(function (payload) {
-          console.log('[mKFashion] addToCart payload:', payload);
-
-          var variantSku = payload.selectedIdentifier;
-          if (!variantSku) {
-            console.warn('[mKFashion] produto sem variantSku — pulando adição ao carrinho');
-            return;
-          }
-
-          // Properties opcionais — passa tamanho/cor se vieram no payload.
-          // No Shopify aparecem no carrinho como propriedades de line item.
-          var properties = {};
-          if (payload.selectedSize) properties['Tamanho'] = payload.selectedSize;
-          if (payload.selectedColor) properties['Cor'] = payload.selectedColor;
-
-          var item = { id: variantSku, quantity: 1 };
-          if (Object.keys(properties).length) item.properties = properties;
-
-          // Endpoint Shopify-style. Ajuste pra sua plataforma:
-          //   VTEX: POST /api/checkout/pub/orderForm/{id}/items
-          //   Wake: API própria
-          //   Magento: rest/V1/carts/mine/items
-          fetch('/cart/add.js', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ items: [item] })
-          })
-            .then(function (response) { return response.json(); })
-            .then(function (data) {
-              console.log('[mKFashion] produto adicionado ao carrinho:', data);
-              // document.dispatchEvent(new CustomEvent('cart:updated'));
-            })
-            .catch(function (error) {
-              console.error('[mKFashion] erro ao adicionar ao carrinho:', error);
-            });
-        });
-
-        mkfashion.onInteraction(function (data) {
-          console.log(data.category, data.action);
-        });
-
-        mkfashion.init({
-          projectId: projectid,
-          identifier: detected.value,
-          target: '#mkfashion-container'
-        });
-      }
-
-      function waitForMkFashion() {
-        if (typeof mkfashion !== 'undefined') {
-          initMkFashion();
-        } else {
-          setTimeout(waitForMkFashion, 100);
-        }
-      }
-
-      if (document.readyState === "loading") {
-        document.addEventListener("DOMContentLoaded", waitForMkFashion);
-      } else {
-        waitForMkFashion();
-      }
-    })();
-  </script>
-
-</body>
-
-</html>
+<!DOCTYPE html>
+<html lang="pt-BR">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Provador Virtual</title>
+  <script src="./src/mkfashion.js"></script>
+</head>
+
+<body>
+
+  <div id="mkfashion-container"></div>
+
+  <script>
+    (function () {
+      var projectid = '69f9e5b0f4eb0c4403319830';
+      var identifier = '1881';
+
+      function initMkFashion() {
+        mkfashion.addToCart(function (payload) {
+          console.log('Adicionando ao carrinho:', payload);
+
+          var variantSku = payload.selectedIdentifier;
+
+          fetch('/cart/add.js', {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              items: [{
+                quantity: 1,
+                id: variantSku
+              }]
+            })
+          })
+            .then(function (response) {
+              return response.json();
+            })
+            .then(function (data) {
+              console.log('Produto adicionado:', data);
+              // document.dispatchEvent(new CustomEvent('cart:updated'));
+            })
+            .catch(function (error) {
+              console.error('Erro carrinho:', error);
+            });
+        });
+
+        mkfashion.onInteraction(function (data) {
+          console.log(data.category, data.action);
+        });
+
+        mkfashion.init({
+          projectId: projectid,
+          identifier: identifier,
+          target: '#mkfashion-container'
+        });
+      }
+
+      function waitForMkFashion() {
+        if (typeof mkfashion !== 'undefined') {
+          initMkFashion();
+        } else {
+          setTimeout(waitForMkFashion, 100);
+        }
+      }
+
+      if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", waitForMkFashion);
+      } else {
+        waitForMkFashion();
+      }
+    })();
+  </script>
+
+</body>
+
+</html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mkfashion-sdk",
-  "version": "2.7.2",
-  "description": "SDK para integrar o provador virtual mKFashion com suporte a Wake Commerce e tracking analytics completo",
+  "version": "2.7.3",
+  "description": "SDK para integrar o provador virtual mKFashion com suporte a Wake Commerce",
   "main": "src/mkfashion.js",
   "scripts": {
     "test": "echo \"Abra test.html no navegador\""