mk-sdk

SDK de tracking de e-commerce + try-on da MetaKosmos. Um único <script> que roda em todas as páginas da loja: mede a jornada de compra (visita → produto → carrinho → compra) e injeta o botão de provador virtual de forma zero-touch.

Publicado no npm como mk-sdk-git e distribuído via CDN (jsDelivr / unpkg).

Instalação

Cole uma linha antes de </head>, em todas as páginas da loja:

<script src="https://cdn.jsdelivr.net/npm/mk-sdk-git@1/dist/mk-sdk.js"
        data-mk-project="SEU_PROJECT_ID"
        data-mk-product="mk-fashion"
        async></script>

• data-mk-project — ID do projeto (obrigatório).
• data-mk-product — produto MetaKosmos da página (mk-fashion, mk-beauty, mk-3d…). Opcional; default mk-fashion.
• async — não bloqueia o carregamento da página.

Versão do CDN

| Forma | URL | Quando usar | |---|---|---| | Major fixo (recomendado) | …/mk-sdk-git@1/dist/mk-sdk.js | Pega o último 1.x.y automaticamente — recebe correções sem quebrar | | Versão exata | …/[email protected]/dist/mk-sdk.js | Trava numa versão específica (imutável) | | unpkg (alternativa) | https://unpkg.com/mk-sdk-git@1/dist/mk-sdk.js | Mesmo pacote, outro CDN |

Evite @latest em produção: cache fraco e risco de um release novo quebrar a loja sem aviso. Prefira o major fixo (@1).

Via bundler (opcional)

npm install mk-sdk-git

O SDK é um IIFE auto-executável feito pra <script>. Num bundler, importe e garanta que window.__MK = { projectId, product } esteja definido antes do import (não há tag <script> pra ler os data-*).

Configuração

Lida do <script> (data-mk-*) ou de window.__MK antes do boot:

| Campo | Origem | Default | |---|---|---| | projectId | data-mk-project / __MK.projectId | — (obrigatório) | | product | data-mk-product / __MK.product | mk-fashion | | collectorUrl | data-mk-collector / __MK.collectorUrl | api-collector.mk3dlabs.com | | apiUrl | __MK.apiUrl | mkfashion-new-api.mk3dlabs.com | | debug | data-mk-debug / ?mkdebug | false | | anchor | __MK.anchor | null (cai no CMS/heurística) |

API pública (window.mk)

mk.open({ projectId, identifier });   // abre o provador
mk.close();
mk.isAvailable(projectId, identifier);
mk.onReady(cb); mk.onAddToCart(cb); mk.onProductLoaded(cb); /* … */

Coleta

Eventos vão em batch (2s ou 20 eventos) para POST {collectorUrl}/v1/track com header X-MK-Project-Id. Dados pessoais (e-mail, CPF, telefone, etc.) são descartados antes do envio.

Build

npm install
npm run build         # gera dist/mk-sdk.js
npm run build:ext     # gera dist + copia pra extension/mk-sdk.js
npm run build:watch   # rebuild em watch

Extensão de QA

extension/ é uma extensão Chrome que injeta o mk-sdk em qualquer loja para validar a integração (tracking, detecção de plataforma/SKU, picker de posição do botão) sem a marca precisar instalar o script. Veja extension/README.md.

Diagnóstico

scripts/ tem sondas (probe-*.js, recon-loja.js) para inspecionar detecção de plataforma/SKU e fluxo de carrinho ao vivo numa loja.