Uma linha no storefront e o catálogo conectado pela API da VTEX. O mK Fashion+ tem módulo dedicado que cobre as três arquiteturas da plataforma, IO, FastStore e Legacy, usando em cada uma o mecanismo de carrinho nativo dela. No IO, o minicart reflete o item adicionado sem recarregar a página.
No head do storefront. Na IO, pelo mecanismo de scripts do tema; na Legacy, no template do head.
<script src="https://unpkg.com/mk-sdk-git@1/dist/mk-sdk.js"
data-mk-project="SEU_PROJECT_ID"
data-mk-product="mk-fashion"
async></script>Troque SEU_PROJECT_ID pelo identificador do seu projeto. O atributo async garante que a tag não bloqueia o carregamento da página, e @1 fixa a major da versão: você recebe correção sem risco de um release novo mudar a loja sem aviso.
A metaKosmos cria o projeto e envia o identificador. Ele é o único valor que muda na tag, e não é segredo: vai no HTML público da loja.
Com as credenciais de API da VTEX, o catálogo é importado com produtos, SKUs, preços e imagens. A importação respeita o limite de requisições da plataforma, então uma loja grande entra sem derrubar a sua cota.
A tag precisa valer em todas as páginas. Onde ela entra depende da arquitetura: na IO, pelo mecanismo de scripts do tema; na Legacy, no template do head. Se a sua operação usa gerenciador de tags, configure o disparo para todas as páginas.
Com o projeto configurado, o botão de provar aparece ao lado do comprar, nos produtos que têm provador. Escolha um tamanho, adicione e confirme duas coisas: que o item entrou com o tamanho certo e que a sacola mostra o produto sem você recarregar a página.
A Legacy publica o produto em objetos globais do tema. A IO é React e não tem esses objetos. A FastStore é headless e guarda o carrinho numa store própria. O módulo reconhece as três e usa o mecanismo nativo de cada uma, então a mesma tag serve para lojas migradas e não migradas.
O id numérico do SKU pode colidir com outro produto do catálogo, e quando colide o botão some de uma peça que tem provador. Por isso a referência do produto vem primeiro e o numérico fica como alternativa, para lojas cujo catálogo é indexado por ele.
Uma página de produto da IO carrega vários contextos de produto, um do item aberto e os demais das vitrines de recomendação. O módulo usa o slug da URL para achar o contexto certo, em vez de pegar o primeiro da árvore, que seria um produto recomendado.
Os dados estruturados da IO trazem o SKU com zeros à esquerda, que não casam com catálogos indexados pelo número limpo. O módulo lê a metatag da plataforma justamente para evitar esse descasamento silencioso.
No storefront React, um item adicionado por API entra no carrinho do servidor mas o minicart continua mostrando o conteúdo antigo até um refresh. A ponte do SDK alcança o mecanismo interno de carrinho do próprio storefront, então a sacola abre já com o item.
A importação controla a própria taxa de requisição contra a API da VTEX. Catálogo grande entra em lote, sem disparar limite de chamadas e sem afetar a operação da loja.
A integração tem duas metades, e elas resolvem problemas distintos.
O catálogo é servidor com servidor: com as credenciais de API, produtos, SKUs, preços e imagens entram, com controle de taxa de requisição para não estourar o limite da plataforma, e re-sincronizam em horário configurado.
A loja é a tag no storefront. Ela roda no navegador do cliente final, identifica o produto, injeta o botão e adiciona ao carrinho pelo mecanismo nativo da arquitetura em que a loja roda.
A VTEX não é uma plataforma só, e é isso que torna a integração dela diferente das outras. Uma loja pode rodar Legacy, IO ou FastStore, e as três guardam o carrinho de um jeito próprio.
Na Legacy, o tema publica o mapa de SKUs e a biblioteca de checkout da própria plataforma. Na IO, o carrinho é gerido por um componente React que faz o POST pela fila dele. Na FastStore, headless, o carrinho vive numa store própria que também controla o contador e a sacola lateral.
O módulo identifica em qual delas a loja está e usa o mecanismo daquela arquitetura, na ordem certa. Não há configuração a fazer e não há nada a instalar no tema: a mesma tag serve para as três.
Na VTEX o mesmo item tem a referência do produto, um código como TF800442-0004, e o id numérico do SKU. Os dois são legítimos e catálogos diferentes indexam por um ou por outro.
A armadilha é que o id numérico pode colidir com outro produto. Quando isso acontece, o provador acha que a peça aberta é outra e, se essa outra não tiver provador, o botão simplesmente some de um produto que tem. Por isso a referência é tentada primeiro e o número fica como alternativa.
Há ainda o detalhe dos zeros à esquerda: os dados estruturados da IO trazem o SKU zerado à esquerda, que não casa com o número limpo. O módulo lê a metatag de SKU da própria plataforma para não cair nesse descasamento.
Na IO, adicionar um item pela API de checkout coloca o produto no carrinho do servidor, mas o minicart não fica sabendo: ele renderiza de um contexto próprio que só rebusca ao montar, e não escuta eventos de fora.
O efeito para o cliente é o pior possível: ele adiciona pelo provador, abre a sacola e não vê o item. Parece que não funcionou, e ele adiciona de novo.
Não existe evento público que force essa atualização, então a solução alcança o mecanismo interno de carrinho do próprio storefront e o aciona de dentro. A sacola abre com o item já lá, sem recarregar a página e sem alteração no tema.
Sim, com módulo dedicado que cobre VTEX IO, FastStore e Legacy, mais conector de catálogo pela API da plataforma. O módulo reconhece sozinho em qual arquitetura a loja roda e usa o mecanismo de carrinho nativo dela.
Nas três. Elas expõem o produto e guardam o carrinho de formas diferentes, e o módulo trata cada uma com o mecanismo nativo, incluindo a ponte que faz o minicart do IO refletir o item adicionado.
Pelos dois. A referência do produto é tentada primeiro, porque o id numérico pode colidir com outro item do catálogo, e o numérico fica como alternativa para lojas indexadas por ele.
Não. A página da IO carrega vários contextos de produto, um do item aberto e os demais das vitrines de recomendação. O módulo usa o slug da URL para achar o contexto correto em vez de pegar o primeiro.
Sim. No storefront React isso exige acionar o mecanismo interno de carrinho, porque o minicart não escuta eventos externos. Sem esse cuidado o cliente abriria a sacola sem ver o item e adicionaria de novo.
Não. A importação controla a própria taxa de requisição contra a API da VTEX, então catálogo grande entra em lote sem disparar o limite.