mkfashion-sdk 2.5.0 → 2.7.1

package/package.json

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

package/src/mkfashion.js

@@ -304,31 +304,24 @@ const mkfashion = {
       const data = await response.json()
       this._log('Disponibilidade recebida', data)
 
-      // Tracking: cada checagem de availability é um sinal de "impressão"
-      // do produto na vitrine. Funciona mesmo se o usuário não clicar.
+      // NOTA: availability check é decisão interna (mostra botão ou não) e
+      // NÃO emite evento pro collector — não traz valor analítico.
+      //
+      // MAS é o gatilho mais comum em PDPs: a partir daqui temos projectId
+      // confirmado e ativamos o auto-tracking (page_view, click, scroll,
+      // form, engagement). Sem isso, páginas onde o usuário só visualiza
+      // (sem clicar no try-on) ficariam invisíveis no collector.
       try {
         if (!this._config) this._config = { projectId: resolved, identifier }
-        this._emitToCollector('availability_checked', {
-          projectId: resolved,
-          identifier,
-          available: data.available === true,
-          reason: data.reason || data.message || null
-        })
+        if (!this._autoTrackInitialized && this.autoTrack !== false) {
+          this._initAutoTrack()
+        }
       } catch (_) {}
 
       return data
 
     } catch (error) {
       console.error('[mKFashion] Erro ao verificar disponibilidade:', error)
-      // Tracking: também emite erros de availability — útil pra detectar 404/500 em prod.
-      try {
-        if (!this._config) this._config = { projectId: resolved, identifier }
-        this._emitToCollector('availability_error', {
-          projectId: resolved,
-          identifier,
-          error: String(error.message || error).slice(0, 200)
-        })
-      } catch (_) {}
       throw error
     }
   },
@@ -621,42 +614,317 @@ const mkfashion = {
   },
 
   /**
-   * Envia evento pro mk-collector-api. Fire-and-forget — nunca atrapalha UX.
-   * Identificação: X-MK-Project-Id (o próprio projectId do mkfashion).
+   * Enfileira evento no batch buffer. O flush real acontece em _flushQueue.
+   * Fire-and-forget — nunca atrapalha UX.
    */
   _emitToCollector(eventName, data) {
     try {
-      if (!this._config || !this._config.projectId) return
+      if (!this._config || !this._config.projectId) {
+        // Antes do projectId estar setado, enfileira pra flush quando estiver.
+        this._preConfigQueue = this._preConfigQueue || []
+        if (this._preConfigQueue.length < 50) {
+          this._preConfigQueue.push({ eventName, data, ts: Date.now() })
+        }
+        return
+      }
       if (!this.collectorUrl) return
 
-      const params = { identifier: this._config.identifier || null }
-      if (data && typeof data === 'object' && !Array.isArray(data)) {
-        Object.assign(params, data)
-      } else if (data !== null && data !== undefined) {
-        params.value = data
+      // Drena qualquer evento que foi enfileirado antes do config existir.
+      if (this._preConfigQueue && this._preConfigQueue.length > 0) {
+        const pending = this._preConfigQueue
+        this._preConfigQueue = []
+        for (const p of pending) this._queueEvent(p.eventName, p.data, p.ts)
       }
 
-      const payload = JSON.stringify({
-        visitorId: this._getVisitorId(),
-        sessionId: this._getSessionId(),
-        events: [{ name: 'sdk_' + eventName, ts: Date.now(), params: params }],
-        site: this._detectSiteContext()
-      })
+      this._queueEvent(eventName, data)
 
-      fetch(this.collectorUrl + '/v1/track/sdk', {
-        method: 'POST',
-        keepalive: true,
-        headers: {
-          'Content-Type': 'application/json',
-          'X-MK-Project-Id': this._config.projectId
-        },
-        body: payload
-      }).catch(() => {})
+      // Auto-start tracking de site no primeiro emit com config.
+      if (!this._autoTrackInitialized && this.autoTrack !== false) {
+        this._initAutoTrack()
+      }
     } catch (e) {
       if (this.debug) console.warn('[mKFashion tracking]', e.message)
     }
   },
 
+  /**
+   * Normaliza nome de evento — tira prefixo "on" e converte camelCase pra snake_case.
+   * Ex: 'onAddToCart' → 'add_to_cart'; 'modal_opened' → 'modal_opened' (já snake).
+   */
+  _normalizeEventName(name) {
+    if (typeof name !== 'string' || !name) return 'unknown'
+    var n = name.replace(/^on/, '')
+    n = n.replace(/[A-Z]/g, function (m, i) { return (i > 0 ? '_' : '') + m.toLowerCase() })
+    if (n.charAt(0) >= 'A' && n.charAt(0) <= 'Z') n = n.toLowerCase()
+    return n
+  },
+
+  /**
+   * Adiciona ao buffer de batch. Flush é disparado por timer ou tamanho.
+   * Todos os eventos recebem prefixo 'page_'.
+   */
+  _queueEvent(eventName, data, tsOverride) {
+    this._eventQueue = this._eventQueue || []
+    const params = { identifier: this._config.identifier || null }
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      Object.assign(params, data)
+    } else if (data !== null && data !== undefined) {
+      params.value = data
+    }
+    this._eventQueue.push({
+      name: 'page_' + this._normalizeEventName(eventName),
+      ts: tsOverride || Date.now(),
+      params: params
+    })
+
+    // Flush sincrono se atingiu limite de tamanho.
+    if (this._eventQueue.length >= 20) {
+      this._flushQueue()
+      return
+    }
+    // Senão, agenda flush em 2s.
+    if (!this._flushTimer) {
+      this._flushTimer = setTimeout(() => { this._flushTimer = null; this._flushQueue() }, 2000)
+    }
+  },
+
+  _flushQueue(useBeacon) {
+    if (!this._eventQueue || this._eventQueue.length === 0) return
+    if (!this._config || !this._config.projectId) return
+    if (!this.collectorUrl) return
+
+    const events = this._eventQueue.splice(0, 50) // máximo 50 por POST
+    const payload = JSON.stringify({
+      visitorId: this._getVisitorId(),
+      sessionId: this._getSessionId(),
+      events: events,
+      site: this._detectSiteContext()
+    })
+
+    const url = this.collectorUrl + '/v1/track/sdk'
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-MK-Project-Id': this._config.projectId
+    }
+
+    // sendBeacon no pagehide pra garantir envio durante unload.
+    if (useBeacon && navigator.sendBeacon) {
+      try {
+        const blob = new Blob([payload], { type: 'application/json' })
+        // sendBeacon nao suporta headers custom — usamos query param.
+        navigator.sendBeacon(url + '?projectId=' + encodeURIComponent(this._config.projectId), blob)
+        return
+      } catch (_) {}
+    }
+
+    fetch(url, { method: 'POST', keepalive: true, headers: headers, body: payload })
+      .catch(() => {})
+  },
+
+  // ============ AUTO-TRACK (pageview/click/scroll/form/engagement) ============
+
+  _autoTrackInitialized: false,
+  _scrollDepthSeen: null,
+  _engagementTimer: null,
+  _engagementLastTick: 0,
+
+  /**
+   * Inicia captura automática de comportamento no site host. Chamado quando
+   * _config recebe um projectId, OU manualmente via mkfashion.startTracking().
+   * Setar mkfashion.autoTrack = false antes do init pra desabilitar.
+   */
+  _initAutoTrack() {
+    if (this._autoTrackInitialized) return
+    this._autoTrackInitialized = true
+    try {
+      this._trackPageview()
+      this._initClickTracking()
+      this._initScrollTracking()
+      this._initFormTracking()
+      this._initEngagementTracking()
+      this._initSpaNavigation()
+      this._initFlushOnUnload()
+      this._log('Auto-tracking iniciado')
+    } catch (e) {
+      if (this.debug) console.warn('[mKFashion auto-track init]', e.message)
+    }
+  },
+
+  /**
+   * API pública pra ativar auto-tracking sem precisar abrir o modal.
+   * Útil em sites onde a SDK só renderiza botão (sem getAvailability) ou
+   * em landing pages sem produto definido.
+   */
+  startTracking(projectId, identifier) {
+    if (!projectId) {
+      console.error('[mKFashion] startTracking: projectId obrigatorio')
+      return
+    }
+    const resolved = this._resolveProjectId(projectId)
+    if (!this._config) this._config = { projectId: resolved, identifier: identifier || null }
+    this._initAutoTrack()
+  },
+
+  _trackPageview() {
+    this._scrollDepthSeen = {}
+    // 'view' aqui vira 'page_view' (prefix 'page_' é adicionado em _queueEvent).
+    this._emitToCollector('view', {
+      url: location.href,
+      pathname: location.pathname,
+      referrer: document.referrer || null,
+      title: document.title || null
+    })
+  },
+
+  _initClickTracking() {
+    if (!document.body) return
+    const INTERACTIVE = { A: 1, BUTTON: 1, INPUT: 1, SELECT: 1, TEXTAREA: 1 }
+    let lastClick = 0
+    document.body.addEventListener('click', (e) => {
+      try {
+        const now = Date.now()
+        if (now - lastClick < 100) return
+        lastClick = now
+        let el = e.target
+        for (let i = 0; i < 5 && el && el !== document.body; i++) {
+          if (INTERACTIVE[el.tagName] || (el.getAttribute && el.getAttribute('role') === 'button')) break
+          el = el.parentElement
+        }
+        if (!el) return
+        if (!INTERACTIVE[el.tagName] && !(el.getAttribute && el.getAttribute('role') === 'button')) return
+
+        const data = { tag: el.tagName }
+        const t = el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' ? el.value : el.textContent
+        data.text = (t || '').replace(/\s+/g, ' ').trim().substring(0, 100)
+        if (el.href) data.href = String(el.href).substring(0, 500)
+        if (el.id) data.id = el.id
+        if (el.className && typeof el.className === 'string') {
+          data.classes = el.className.trim().substring(0, 200)
+        }
+        this._emitToCollector('click', data)
+      } catch (_) {}
+    }, { capture: true, passive: true })
+  },
+
+  _initScrollTracking() {
+    const TH = [25, 50, 75, 100]
+    let scrollTimer = null
+    const check = () => {
+      try {
+        const sy = window.scrollY || document.documentElement.scrollTop || 0
+        const dh = Math.max(
+          document.body && document.body.scrollHeight || 0,
+          document.documentElement && document.documentElement.scrollHeight || 0
+        )
+        if (dh <= 0) return
+        const p = Math.min(100, Math.floor((sy + window.innerHeight) / dh * 100))
+        if (!this._scrollDepthSeen) this._scrollDepthSeen = {}
+        for (const t of TH) {
+          if (p >= t && !this._scrollDepthSeen[t]) {
+            this._scrollDepthSeen[t] = true
+            this._emitToCollector('scroll_depth', { depth: t })
+          }
+        }
+      } catch (_) {}
+    }
+    check()
+    window.addEventListener('scroll', () => {
+      if (scrollTimer) return
+      scrollTimer = setTimeout(() => { scrollTimer = null; check() }, 250)
+    }, { passive: true })
+  },
+
+  _initFormTracking() {
+    if (!document.body) return
+    const CC = ['wpcf7-form', 'wpforms-form', 'gform_wrapper', 'formidable']
+    const NP = ['subscribe', 'newsletter', 'mailchimp', 'convertkit']
+    document.body.addEventListener('submit', (e) => {
+      try {
+        const f = e.target
+        if (!f || f.tagName !== 'FORM') return
+        // Skip WooCommerce checkout (capturado por outro caminho)
+        if (f.classList && (f.classList.contains('woocommerce-checkout') ||
+                            f.classList.contains('wc-block-checkout__form'))) return
+
+        let ft = 'other'
+        const cls = f.className || ''
+        const act = (f.action || '').toLowerCase()
+        if (f.querySelector('input[type="search"]') || f.querySelector('input[name="s"]')) ft = 'search'
+        else {
+          for (const c of CC) if (cls.indexOf(c) !== -1) { ft = 'contact'; break }
+          if (ft === 'other') for (const n of NP) if (act.indexOf(n) !== -1) { ft = 'newsletter'; break }
+        }
+        this._emitToCollector('form_submit', {
+          form_id: f.id || '',
+          form_action: (f.action || '').substring(0, 300),
+          form_type: ft
+        })
+      } catch (_) {}
+    }, { capture: true })
+  },
+
+  _initEngagementTracking() {
+    const INTERVAL = 15000
+    this._engagementLastTick = Date.now()
+    this._engagementTimer = setInterval(() => {
+      if (document.hidden) return
+      const now = Date.now()
+      const elapsedSec = Math.round((now - this._engagementLastTick) / 1000)
+      this._engagementLastTick = now
+      if (elapsedSec > 0 && elapsedSec < 60) {
+        this._emitToCollector('engagement', { url: location.pathname, dwellSec: elapsedSec })
+      }
+    }, INTERVAL)
+
+    document.addEventListener('visibilitychange', () => {
+      if (document.hidden) {
+        const elapsedSec = Math.round((Date.now() - this._engagementLastTick) / 1000)
+        if (elapsedSec > 0 && elapsedSec < 600) {
+          this._emitToCollector('engagement', { url: location.pathname, dwellSec: elapsedSec })
+        }
+        this._engagementLastTick = Date.now()
+      } else {
+        this._engagementLastTick = Date.now()
+      }
+    })
+  },
+
+  _initSpaNavigation() {
+    // Captura SPA navigation (React/Vue/Next/etc) emitindo page_view a cada
+    // mudança de URL via history API.
+    let lastUrl = location.href
+    const self = this
+    const onChange = () => {
+      if (location.href !== lastUrl) {
+        lastUrl = location.href
+        self._trackPageview()
+      }
+    }
+    try {
+      const origPush = history.pushState
+      const origReplace = history.replaceState
+      history.pushState = function () { origPush.apply(this, arguments); setTimeout(onChange, 0) }
+      history.replaceState = function () { origReplace.apply(this, arguments); setTimeout(onChange, 0) }
+      window.addEventListener('popstate', onChange)
+    } catch (_) {}
+  },
+
+  _initFlushOnUnload() {
+    // Flush sincrono no pagehide pra não perder engagement final + qualquer evento pendente.
+    window.addEventListener('pagehide', () => {
+      try {
+        const elapsedSec = Math.round((Date.now() - this._engagementLastTick) / 1000)
+        if (elapsedSec > 0 && elapsedSec < 600) {
+          this._emitToCollector('engagement', { url: location.pathname, dwellSec: elapsedSec })
+        }
+        this._flushQueue(true)
+      } catch (_) {}
+    })
+    window.addEventListener('beforeunload', () => {
+      try { this._flushQueue(true) } catch (_) {}
+    })
+  },
+
   _buildUrl() {
     const encoded = encodeURIComponent(this._config.identifier).replace(/\./g, '%2E')
     const url = `${this.appUrl}/${this._config.projectId}/${encoded}`