mkfashion-sdk 2.7.4 → 2.7.5

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

@@ -1,311 +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)
+# 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/gtm-snippet.js

@@ -1,116 +1,116 @@
-/**
- * mKFashion SDK — Injection Snippet (versão compacta)
- *
- * Auto-detecta o SKU do produto na PDP, carrega o SDK e renderiza o botão.
- * Quando o cliente adiciona ao carrinho dentro do provador, faz POST
- * pra /cart/add.js com tamanho/cor se disponíveis.
- *
- * USO: cole o conteúdo no GTM (Custom HTML tag), no console DevTools de
- * uma PDP, ou converta pra bookmarklet.
- *
- * CONFIG: troque SEU_PROJECT_ID pelo projectId real do mKFashion.
- */
-(function () {
-  // Pode ser sobrescrito setando window.MKFASHION_PROJECT_ID antes deste script
-  // (útil pra GTM Variables ou ambientes de teste).
-  var PROJECT_ID = window.MKFASHION_PROJECT_ID || 'SEU_PROJECT_ID';
-
-  if (window.mkfashion) return go();
-  var s = document.createElement('script');
-  s.src = 'https://unpkg.com/mkfashion-sdk/src/mkfashion.js';
-  s.async = true;
-  s.onload = go;
-  document.head.appendChild(s);
-
-  // Detecta SKU do produto na PDP, em ordem de prioridade.
-  function detect() {
-    // 1. Override manual via ?sku= ou ?identifier=
-    var qs = new URLSearchParams(location.search);
-    if (qs.get('sku')) return qs.get('sku');
-    if (qs.get('identifier')) return qs.get('identifier');
-
-    // 2. Konfidency (Marisa, Renner e outras marcas BR usam esse serviço de reviews)
-    if (window.konfidencyData && window.konfidencyData.sku) {
-      return String(window.konfidencyData.sku);
-    }
-
-    // 3. dataLayer (GA4 / Universal Analytics Enhanced Ecommerce)
-    if (window.dataLayer) {
-      for (var i = window.dataLayer.length - 1; i >= 0; i--) {
-        var x = (window.dataLayer[i] || {}).ecommerce;
-        if (!x) continue;
-        var p = (x.detail && x.detail.products && x.detail.products[0]) ||
-                (x.items && x.items[0]);
-        if (p) return String(p.id || p.item_id);
-      }
-    }
-
-    // 4. JSON-LD Schema.org Product
-    var lds = document.querySelectorAll('script[type="application/ld+json"]');
-    for (var j = 0; j < lds.length; j++) {
-      try {
-        var items = [].concat(JSON.parse(lds[j].textContent));
-        for (var k = 0; k < items.length; k++) {
-          var pr = items[k]['@type'] === 'Product' ? items[k] :
-            (items[k]['@graph'] || []).find(function (g) { return g['@type'] === 'Product'; });
-          if (pr && (pr.sku || pr.productID)) return String(pr.sku || pr.productID);
-        }
-      } catch (e) {}
-    }
-
-    return null;
-  }
-
-  function go() {
-    var sku = detect();
-    if (!sku) {
-      console.error('[mKFashion] SKU não detectado. Tente passar ?sku=SEU_SKU na URL.');
-      return;
-    }
-    console.log('[mKFashion] SKU:', sku);
-
-    // Cria container se ainda não existe (overlay fixo no canto como fallback)
-    if (!document.getElementById('mkfashion-container')) {
-      var c = document.createElement('div');
-      c.id = 'mkfashion-container';
-      c.style.cssText = 'position:fixed;top:90px;right:20px;z-index:99999;background:#fff;padding:8px;border-radius:8px;box-shadow:0 4px 20px rgba(0,0,0,.12)';
-      document.body.appendChild(c);
-    }
-
-    // Adiciona ao carrinho da plataforma com tamanho/cor se disponíveis
-    mkfashion.addToCart(function (p) {
-      console.log('[mKFashion] addToCart:', p);
-      var item = { id: p.selectedIdentifier, quantity: 1 };
-      var props = {};
-      if (p.selectedSize) props['Tamanho'] = p.selectedSize;
-      if (p.selectedColor) props['Cor'] = p.selectedColor;
-      if (Object.keys(props).length) item.properties = props;
-
-      // Endpoint Shopify-style. Para VTEX/Wake/Magento, ajuste a URL e o body.
-      fetch('/cart/add.js', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ items: [item] })
-      })
-        .then(function (r) { return r.json(); })
-        .then(function (d) { console.log('[mKFashion] no carrinho:', d); })
-        .catch(function (e) { console.error('[mKFashion] erro cart:', e); });
-    });
-
-    mkfashion.init({
-      projectId: PROJECT_ID,
-      identifier: sku,
-      target: '#mkfashion-container'
-    }).then(function (r) {
-      // Workaround: depois do init() já validar availability, evita re-fetch no
-      // click handler. Sem isso, em sites com monitor SPA (New Relic, etc.) o
-      // click intercepta o documento e quebra o fetch com "global scope shutting
-      // down". Redundante na SDK 2.5.x+ (cache nativo) — mas inofensivo.
-      if (r && r.ok) {
-        mkfashion.getAvailability = function () {
-          return Promise.resolve({ available: true });
-        };
-      }
-    });
-  }
-})();
+/**
+ * mKFashion SDK — Injection Snippet (versão compacta)
+ *
+ * Auto-detecta o SKU do produto na PDP, carrega o SDK e renderiza o botão.
+ * Quando o cliente adiciona ao carrinho dentro do provador, faz POST
+ * pra /cart/add.js com tamanho/cor se disponíveis.
+ *
+ * USO: cole o conteúdo no GTM (Custom HTML tag), no console DevTools de
+ * uma PDP, ou converta pra bookmarklet.
+ *
+ * CONFIG: troque SEU_PROJECT_ID pelo projectId real do mKFashion.
+ */
+(function () {
+  // Pode ser sobrescrito setando window.MKFASHION_PROJECT_ID antes deste script
+  // (útil pra GTM Variables ou ambientes de teste).
+  var PROJECT_ID = window.MKFASHION_PROJECT_ID || 'SEU_PROJECT_ID';
+
+  if (window.mkfashion) return go();
+  var s = document.createElement('script');
+  s.src = 'https://unpkg.com/mkfashion-sdk/src/mkfashion.js';
+  s.async = true;
+  s.onload = go;
+  document.head.appendChild(s);
+
+  // Detecta SKU do produto na PDP, em ordem de prioridade.
+  function detect() {
+    // 1. Override manual via ?sku= ou ?identifier=
+    var qs = new URLSearchParams(location.search);
+    if (qs.get('sku')) return qs.get('sku');
+    if (qs.get('identifier')) return qs.get('identifier');
+
+    // 2. Konfidency (Marisa, Renner e outras marcas BR usam esse serviço de reviews)
+    if (window.konfidencyData && window.konfidencyData.sku) {
+      return String(window.konfidencyData.sku);
+    }
+
+    // 3. dataLayer (GA4 / Universal Analytics Enhanced Ecommerce)
+    if (window.dataLayer) {
+      for (var i = window.dataLayer.length - 1; i >= 0; i--) {
+        var x = (window.dataLayer[i] || {}).ecommerce;
+        if (!x) continue;
+        var p = (x.detail && x.detail.products && x.detail.products[0]) ||
+                (x.items && x.items[0]);
+        if (p) return String(p.id || p.item_id);
+      }
+    }
+
+    // 4. JSON-LD Schema.org Product
+    var lds = document.querySelectorAll('script[type="application/ld+json"]');
+    for (var j = 0; j < lds.length; j++) {
+      try {
+        var items = [].concat(JSON.parse(lds[j].textContent));
+        for (var k = 0; k < items.length; k++) {
+          var pr = items[k]['@type'] === 'Product' ? items[k] :
+            (items[k]['@graph'] || []).find(function (g) { return g['@type'] === 'Product'; });
+          if (pr && (pr.sku || pr.productID)) return String(pr.sku || pr.productID);
+        }
+      } catch (e) {}
+    }
+
+    return null;
+  }
+
+  function go() {
+    var sku = detect();
+    if (!sku) {
+      console.error('[mKFashion] SKU não detectado. Tente passar ?sku=SEU_SKU na URL.');
+      return;
+    }
+    console.log('[mKFashion] SKU:', sku);
+
+    // Cria container se ainda não existe (overlay fixo no canto como fallback)
+    if (!document.getElementById('mkfashion-container')) {
+      var c = document.createElement('div');
+      c.id = 'mkfashion-container';
+      c.style.cssText = 'position:fixed;top:90px;right:20px;z-index:99999;background:#fff;padding:8px;border-radius:8px;box-shadow:0 4px 20px rgba(0,0,0,.12)';
+      document.body.appendChild(c);
+    }
+
+    // Adiciona ao carrinho da plataforma com tamanho/cor se disponíveis
+    mkfashion.addToCart(function (p) {
+      console.log('[mKFashion] addToCart:', p);
+      var item = { id: p.selectedIdentifier, quantity: 1 };
+      var props = {};
+      if (p.selectedSize) props['Tamanho'] = p.selectedSize;
+      if (p.selectedColor) props['Cor'] = p.selectedColor;
+      if (Object.keys(props).length) item.properties = props;
+
+      // Endpoint Shopify-style. Para VTEX/Wake/Magento, ajuste a URL e o body.
+      fetch('/cart/add.js', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ items: [item] })
+      })
+        .then(function (r) { return r.json(); })
+        .then(function (d) { console.log('[mKFashion] no carrinho:', d); })
+        .catch(function (e) { console.error('[mKFashion] erro cart:', e); });
+    });
+
+    mkfashion.init({
+      projectId: PROJECT_ID,
+      identifier: sku,
+      target: '#mkfashion-container'
+    }).then(function (r) {
+      // Workaround: depois do init() já validar availability, evita re-fetch no
+      // click handler. Sem isso, em sites com monitor SPA (New Relic, etc.) o
+      // click intercepta o documento e quebra o fetch com "global scope shutting
+      // down". Redundante na SDK 2.5.x+ (cache nativo) — mas inofensivo.
+      if (r && r.ok) {
+        mkfashion.getAvailability = function () {
+          return Promise.resolve({ available: true });
+        };
+      }
+    });
+  }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkfashion-sdk",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "SDK para integrar o provador virtual mKFashion com suporte a Wake Commerce",
   "main": "src/mkfashion.js",
   "scripts": {

package/src/mkfashion.js

@@ -21,6 +21,12 @@ const mkfashion = {
   apiUrl: 'https://mkfashion-new-api.mk3dlabs.com',
   debug: false,
 
+  // GA4 do mkfashion (mesmo ID do visualizer/index.html). Usado pra disparar
+  // experience_clicked, que ocorre ANTES do iframe carregar — sem isto, esse evento
+  // cairia apenas no GA da loja (se houver), nao no nosso.
+  _MK_GA_ID: 'G-LPV8HY4JPQ',
+  _gaInitialized: false,
+
   // STAGING - ativado via ?mkStaging=true na URL da página (ver bloco no final)
   stagingAppUrl: 'https://mkfashion.metakosmoslab.com/visualizer',
   stagingApiUrl: 'https://mkfashion-api.metakosmoslab.com',
@@ -43,6 +49,8 @@ const mkfashion = {
   _messageHandler: null,
   _confirmingExit: false,
   _projectIdOverride: null,    // sobrescreve projectId via ?mkProjectId= (QA/teste)
+  _orientation: 'portrait',    // 'portrait' | 'landscape' (apenas desktop usa resize via SDK)
+  _portraitDimensions: null,   // { width, height } salvos pra restaurar ao voltar de landscape
 
   _callbacks: {
     onReady: null,
@@ -85,6 +93,11 @@ const mkfashion = {
       return
     }
 
+    // Track de intencao ANTES do availability check: captura todo clique no botao
+    // (inclusive em produtos indisponiveis). Complementa o experience_started, que so
+    // dispara quando o iframe carrega — a diferenca entre os dois mostra o drop-off.
+    this._trackExperienceClicked(projectId, identifier)
+
     try {
       const availability = await this.getAvailability(projectId, identifier)
       if (!availability.available) {
@@ -399,6 +412,52 @@ const mkfashion = {
 
   // ============ METODOS PRIVADOS ============
 
+  /**
+   * Garante o gtag.js do mkfashion no contexto da loja (idempotente).
+   * Se a loja ja tem gtag proprio, reusa window.gtag e so adiciona NOSSO id via config
+   * com send_page_view:false (nao infla pageviews da loja). Eventos usam send_to pra
+   * nao vazar pro GA da loja.
+   */
+  _ensureGa() {
+    if (this._gaInitialized || typeof window === 'undefined') return
+
+    if (typeof window.gtag !== 'function') {
+      const script = document.createElement('script')
+      script.async = true
+      script.src = `https://www.googletagmanager.com/gtag/js?id=${this._MK_GA_ID}`
+      document.head.appendChild(script)
+      window.dataLayer = window.dataLayer || []
+      window.gtag = function () { window.dataLayer.push(arguments) }
+      window.gtag('js', new Date())
+    }
+    window.gtag('config', this._MK_GA_ID, { send_page_view: false })
+    this._gaInitialized = true
+  },
+
+  /** Dispara experience_clicked no GA4 do mkfashion + callback onInteraction da loja. */
+  _trackExperienceClicked(projectId, identifier) {
+    try {
+      this._ensureGa()
+      if (typeof window !== 'undefined' && typeof window.gtag === 'function') {
+        window.gtag('event', 'experience_clicked', {
+          send_to: this._MK_GA_ID,
+          project_id: projectId || 'unknown',
+          product_id: identifier || 'unknown'
+        })
+      }
+    } catch (error) {
+      console.error('[mKFashion] Erro ao registrar experience_clicked:', error)
+    }
+    this._triggerCallback('onInteraction', {
+      category: 'experience',
+      action: 'click',
+      projectId,
+      identifier,
+      product_id: identifier || 'unknown',
+      project_id: projectId || 'unknown'
+    })
+  },
+
   _log(message, data = null) {
     if (this.debug) {
       if (data) {
@@ -584,6 +643,46 @@ const mkfashion = {
     )
   },
 
+  /**
+   * Desktop: alterna o iframe/modal entre portrait e um formato widescreen (landscape).
+   * Em landscape usa ~90vw x 9/16, limitado, centralizado. Idempotente.
+   * Mobile NAO usa isto — la a rotacao eh fisica (fullscreen + orientation.lock no iframe).
+   */
+  _setIframeOrientation(orientation) {
+    if (this._orientation === orientation) return
+    if (!this._container || !this._iframe) return
+
+    if (orientation === 'landscape') {
+      if (!this._portraitDimensions) {
+        this._portraitDimensions = {
+          width: this._container.style.width || `${this._config?.width || 430}px`,
+          height: this._container.style.height || `${this._config?.height || 800}px`
+        }
+      }
+      // Widescreen: ocupa boa parte da viewport mantendo 16:9, sem estourar a tela.
+      const w = Math.min(window.innerWidth * 0.92, 960)
+      const h = Math.min(w * 9 / 16, window.innerHeight * 0.92)
+      this._applyContainerSize(`${Math.round(w)}px`, `${Math.round(h)}px`)
+    } else {
+      const dims = this._portraitDimensions || { width: '430px', height: '800px' }
+      this._applyContainerSize(dims.width, dims.height)
+    }
+
+    this._orientation = orientation
+    this._log(`Orientacao do iframe: ${orientation}`)
+  },
+
+  _applyContainerSize(width, height) {
+    if (this._container) {
+      this._container.style.width = width
+      this._container.style.height = height
+    }
+    if (this._iframe) {
+      this._iframe.style.width = width
+      this._iframe.style.height = height
+    }
+  },
+
   /** Esconde o modal sem remover do DOM (preserva sessao do iframe) */
   _hideModal() {
     if (!this._modal) return
@@ -637,6 +736,8 @@ const mkfashion = {
     this._container = null
     this._lastConfig = null
     this._confirmingExit = false
+    this._orientation = 'portrait'
+    this._portraitDimensions = null
 
     if (this._escHandler) {
       document.removeEventListener('keydown', this._escHandler)
@@ -650,7 +751,10 @@ const mkfashion = {
     iframe.style.width = typeof width === 'number' ? `${width}px` : width
     iframe.style.height = typeof height === 'number' ? `${height}px` : height
     iframe.style.border = 'none'
-    iframe.setAttribute('allow', 'camera *; microphone *')
+    // fullscreen necessario pro "Ver na horizontal" do fluxo de moveis em mobile:
+    // o visualizer chama requestFullscreen + screen.orientation.lock de dentro do iframe
+    // (aproveitando o gesto do clique local) pra girar a tela no Android.
+    iframe.setAttribute('allow', 'camera *; microphone *; web-share *; fullscreen *')
     iframe.setAttribute('allowfullscreen', 'true')
     return iframe
   },
@@ -679,6 +783,14 @@ const mkfashion = {
           this.restart()
           break
 
+        case 'request_orientation':
+          // Usado pelo fluxo de moveis (furniture) no DESKTOP, onde girar a tela nao faz
+          // sentido: o SDK so redimensiona o iframe/modal pra um formato widescreen.
+          // Em mobile a rotacao acontece dentro do iframe (fullscreen + orientation.lock),
+          // entao mobile nao manda esta mensagem.
+          this._setIframeOrientation(data === 'landscape' ? 'landscape' : 'portrait')
+          break
+
         case 'ready':
           this._log('App pronta', data)
           this._triggerCallback('onReady', data)