VTEX e o desafio do tamanho em moda
VTEX é a plataforma dominante de e-commerce no varejo brasileiro de moda médio e enterprise. Marcas como C&A, Renner, Lojas Riachuelo, Hering, Marisa, AMARO, Le Lis e dezenas de DTCs operam em VTEX IO ou CMS Portal Legacy. Apesar do tamanho do mercado, a recomendação de tamanho continua mal resolvida: a maioria das lojas exibe um modal estático com tabela genérica, e a devolução por tamanho segue como principal motivo de troca.
Este guia cobre integração do Provou em VTEX, com atenção aos dois ambientes ativos da plataforma: VTEX IO (storefront moderno em React) e CMS Portal Legacy (.NET / template HTML). O snippet final é o mesmo (uma linha), mas o ponto de inserção e a forma de gerenciar diferem.
Provou é uma tag de script com 18 KB gzip, render em Shadow DOM e zero acoplamento ao framework do storefront. Funciona em VTEX sem nenhuma adaptação proprietária.
VTEX IO vs CMS Portal: onde colar
Antes de instalar, identifique em qual stack sua loja roda:
- VTEX IO: storefront em React, build via VTEX Toolbelt, blocos declarativos em
store.json. Características: arquivos.tsxem apps de tema, configuração viavtex.store-theme. - CMS Portal Legacy: storefront em template HTML editado via
/admin/Site/Edit.aspx, header.html / footer.html / template-product.html. Caracteristicas: editor visual de templates, sem build process moderno.
Existem três pontos de inserção viáveis:
- Pixel App (recomendado para IO): app dedicado a injetar scripts de terceiros, com lifecycle gerenciado.
- Custom HTML em vtex.store-header (IO): bloco custom-html no header.
- Header.html ou template HTML (CMS Portal): edição direta do template.
Passo a passo: Pixel App ou Custom HTML
O snippet base do Provou:
``html <script src="https://cdn.provou.app.br/v1.js" data-store="sua-loja" async></script> ``
Caminho VTEX IO: Pixel App personalizado
A forma canônica em VTEX IO é criar (ou usar existente) um Pixel App. Pixels recebem eventos da loja e podem injetar scripts.
- Clone o template oficial:
vtex io init pixel-app provou-pixel. - No
pixel.tsx, adicione o injeção do snippet:
```tsx import { canUseDOM } from 'vtex.render-runtime';
if (canUseDOM && !document.querySelector('[data-provador="provou"]')) { const s = document.createElement('script'); s.src = 'https://cdn.provou.app.br/v1.js'; s.async = true; s.dataset.store = 'sua-loja'; s.dataset.provador = 'provou'; document.head.appendChild(s); } ```
- Publique o app:
vtex publish && vtex install seu.vendor.provou-pixel. - Ative em Loja > Pixels no admin.
Vantagem: o pixel é gerenciado, sem editar tema base, fácil de ativar/desativar.
Como alternativa rápida sem app próprio, edite store/blocks/header.jsonc e adicione um html block com o snippet bruto. Em apps customizados de tema, isso é frequentemente já permitido.
Caminho CMS Portal: template HTML
- Acesse Admin > Catalogo > Loja > Lojas e canais e identifique sua loja ativa.
- Em Loja > Templates, abra Header (cabeçalho).
- Cole o snippet imediatamente antes do
</head>(ou no<head>no topo). - Salve e publique.
Em CMS Portal, o template é compartilhado por todas as páginas. Uma única edição cobre catálogo, PDP, busca e checkout.
Importação de tabelas via Catalog API
VTEX expõe a Catalog API para automação. O Provou aceita três fontes:
- Catalog API (recomendado para enterprise): o Provou consulta SKUs, especificações e variantes via REST.
- Feed GMC: se sua loja exporta para Google Shopping, basta apontar o feed.
- CSV upload: caminho rápido para validação inicial.
Para Catalog API, gere uma chave/token no admin VTEX (perfil com permissão de leitura de catálogo). Forneça ao Provou no painel. A sincronização inicial pode levar de 5 a 30 minutos, dependendo do tamanho do catálogo.
Para entender estrutura de tabela e modelagem, consulte o guia sobre tabela de medidas.
PDP em vtex.product-details
A PDP padrão do tema VTEX IO usa vtex.product-details. O widget Provou ancora-se ao seletor de SKU (variantes) ou ao botão de comprar via querystring de DOM ([data-product-id], [data-sku], classe .product-skuselector).
Em PDPs altamente customizadas, você pode forçar o ponto de ancoragem com:
``html <div data-provou-anchor="provador"></div> ``
E configurar o slug provador no painel. O widget renderiza nesse container.
Performance e Core Web Vitals
VTEX IO usa SSR + hidratação em React. Scripts de terceiros mal calibrados podem degradar INP e LCP. O Provou foi calibrado para zero impacto:
- Async, não bloqueia hidratação.
- 18 KB gzip total.
- Shadow DOM, sem reflow no DOM principal.
- Edge CDN no Brasil, latência abaixo de 60 ms para SP/RJ.
- Lazy init: hidrata só quando o usuário interage.
Em testes em lojas VTEX IO em produção, scores Lighthouse Mobile não mudam pré e pós-instalação. Para auditar, use o guia de aumento de conversão que detalha métricas.
Workspace e como testar
VTEX IO tem o conceito de workspaces (branches do storefront). Use-os para testar o Provou sem afetar produção:
- Crie workspace de teste:
vtex use teste-provou. - Linke o app pixel:
vtex link. - Acesse a loja via URL com workspace:
https://teste-provou--seuvendor.myvtex.com. - Valide PDP, mobile e desktop.
- Promote o workspace para produção:
vtex promote teste-provou.
Em CMS Portal, não há workspace. Use ambiente de homologação separado se sua loja tiver, ou agende janela de baixo tráfego.
Boas práticas e troubleshooting
Widget não aparece na PDP. Verifique no DevTools se v1.js carregou. Se sim, confirme o slug em data-store. Se não, investigue Content Security Policy (CSP): VTEX permite domínios de terceiros via app de Headers.
Conflito com app concorrente. Se já há outra ferramenta de tamanho instalada, desinstale ou desabilite antes para evitar conflito de UI.
Variantes não disparam recomendação. Confirme que o ponto de ancoragem captura o evento de mudança de SKU. Em temas customizados, ajuste o seletor.
CSP bloqueia o script. Adicione cdn.provou.app.br ao script-src na configuração de Headers do storefront.
Para testar como tudo isso parece, abra a demo ao vivo. Para começar a integração, faça o cadastro gratuito (14 dias, sem cartão) e copie seu slug. Em pouco mais de uma hora você está rodando em workspace.
Métricas e analytics em VTEX
VTEX expõe o objeto vtex.store-events (em IO) e o dataLayer em CMS Portal. O Provou emite cinco eventos client-side (widget_loaded, widget_opened, chart_viewed, recommendation_computed, widget_closed) que você encaminha a GA4, Meta Pixel ou ferramentas de analytics enterprise (Adobe Analytics, Looker, Snowflake) via VTEX Pixel Apps.
Em VTEX IO, a instrumentação canônica passa por uma Pixel App customizada que escuta os eventos e os repassa via vtex.pixel-manager:
``tsx window.addEventListener('provou:event', (e) => { if (window.vtex?.pixelManager?.publish) { window.vtex.pixelManager.publish({ event: 'provou_' + e.detail.name, ...e.detail.payload, }); } }); ``
KPIs primários a monitorar:
- Adoção do widget: % de visitantes da PDP que abriram o widget. Esperado: 10% a 18% em moda.
- Completude: % que terminaram o fluxo das quatro medidas. Esperado: 70% a 85% dos que abriram.
- Adoção da recomendação: % que escolheram o tamanho sugerido. Esperado: 65% a 80%.
- Lift de conversão: diferença na taxa de compra entre cohorts que usaram e não usaram o widget. Esperado: +2 a +4 pp.
- Redução de devoluções por tamanho: monitorar em janelas de 60 a 90 dias. Esperado: -25% a -42%.
Em VTEX Plus enterprise, a sincronização com Master Data permite cruzar os eventos com perfil do cliente, CLV e cohort por canal (App, Web, marketplace). Para detalhes do cálculo financeiro, consulte o guia de ROI.
Casos comuns em moda VTEX
VTEX abriga três perfis que dominam o varejo de moda brasileiro:
Redes nacionais com múltiplas lojas e canais (C&A, Renner, Lojas Riachuelo, Hering, Marisa). Catálogos com mais de 30 mil SKUs ativos, múltiplas marcas próprias e licenciadas, presença em web, app e marketplace. Para esse perfil, a integração via Pixel App garante governança e consistência entre canais. O Provou conecta-se à Catalog API e mantém a base de tabelas atualizada via webhook.
Multimarcas e e-commerces premium (AMARO, Le Lis, Animale, Schutz e similares). Catálogos médios com identidade visual sofisticada, modelagem inclusiva, sazonalidade marcada. O Provou rende mais quando combinado com fotos consistentes em mesma modelo, ficha técnica detalhada e política de troca clara. Para o panorama de troca, leia trocas e devoluções em 2026.
Operações multi-store em VTEX (mesmo grupo, várias bandeiras com tabelas distintas). VTEX permite escopos por store view, e o Provou suporta múltiplos slugs por instalação. Cada bandeira mantém sua tabela de medidas independente, com governança centralizada via API.
Para qualquer dessas operações, o caminho técnico inicia em /preview (validação visual) e /register (cadastro 14 dias grátis). Em uma sprint, a Pixel App está em workspace; em duas, em produção.
VTEX entrega o framework. Provou entrega o tamanho certo. Juntos, devolução por tamanho deixa de ser o motivo principal de troca. Veja também os guias de Shopify e Magento no blog para comparar abordagens entre plataformas.