Uma linha colada em Códigos externos, no painel da loja. O mK Fashion+ tem módulo dedicado à Nuvemshop que lê o SKU da variante selecionada, adiciona ao carrinho pelo fluxo AJAX do próprio tema e deixa o mini-cart abrir sozinho. Sem app, sem editar template.
No painel: Configurações > Códigos externos > Cabeçalho.
<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.
A instalação do app da metaKosmos na loja autoriza a leitura do catálogo por OAuth e importa produtos, variantes, preços, imagens e categorias. A loja avisa por webhook quando algo muda, e a re-sincronização roda em horário configurado por projeto.
No painel da Nuvemshop: Configurações > Códigos externos > Cabeçalho. É o campo que a própria plataforma oferece para script de terceiro, então nenhum arquivo de tema é alterado e a tag vale em todas as páginas.
Com o projeto configurado, o botão de provar aparece sozinho ao lado do comprar, nos produtos que têm provador. Troque a variação, abra o provador, escolha um tamanho e confira o item no mini-cart.
Na listagem e na home, o provador pode ser aberto a partir do card. Vale testar adicionar por ali e confirmar que o item que entra na sacola é o do card aberto, não o primeiro da página.
O app instalado na loja autoriza a leitura do catálogo e importa produtos, variantes, preços, imagens e categorias. Produto novo e troca de preço chegam sem ninguém reimportar planilha.
O campo de Códigos externos é da própria plataforma. Nada de duplicar tema, abrir editor de código ou pedir deploy: cola, salva e está valendo.
A página de produto da Nuvemshop costuma publicar dados estruturados dos produtos relacionados, não do produto aberto. O adapter ignora essa fonte de propósito e espera os dados reais da variante carregarem, então o botão nunca aparece numa peça que não tem provador.
O identificador é o SKU textual da variante selecionada, lido do próprio estado da loja. É o mesmo código que a sua equipe já usa no painel, sem tradução no meio.
O adapter preenche a variação, espera o tema recalcular e aciona o botão de compra nativo. Quem adiciona é o AJAX do tema, então o carrinho, o contador e a sacola ficam consistentes sem esforço.
Como a Nuvemshop já abre a sacola depois de adicionar, não há redirecionamento para a página de carrinho. O provador segue aberto para a avaliação e o item está lá quando o cliente fecha.
Quando o provador é aberto de um card na listagem ou na home, a adição encontra o card certo pelo identificador do produto provado, em vez de cair no primeiro card da página.
A integração tem duas metades, e elas resolvem problemas distintos.
O catálogo é servidor com servidor. O app instalado na loja autoriza a leitura por OAuth e importa produtos, variantes, preços, imagens e categorias, com webhook avisando o que mudou. É o que faz o provador saber que peça é aquela, com que grade e com que foto.
A loja é a tag colada em Códigos externos. Ela roda no navegador do cliente final, reconhece a página de produto, injeta o botão e adiciona ao carrinho.
As duas se encontram no SKU da variante: o mesmo código que veio da API da Nuvemshop é o que a tag lê da página. Por isso não existe planilha de URLs públicas para manter em sincronia.
O mk-sdk é um script único que roda em todas as páginas da loja. Ao carregar, ele identifica a Nuvemshop pelo estado que a própria plataforma publica na página e passa a usar o módulo dedicado a ela.
A partir daí, tudo que o provador precisa vem da página: o SKU da variante selecionada e o caminho de adicionar ao carrinho.
Esse é o detalhe mais específico da Nuvemshop. Os dados estruturados que a página de produto publica costumam descrever os produtos do carrossel de recomendação, não o produto que está aberto.
Um provador que lesse essa fonte pegaria o código de outra peça. E se essa outra peça tivesse provador, o botão apareceria numa página onde ele não deveria estar, abrindo a experiência com o produto errado. Foi exatamente o que aconteceu numa loja durante a integração: uma bolsa sem provador exibia o botão porque os dados estruturados traziam outro item.
Por isso o adapter não usa essa fonte em hipótese nenhuma. Ele espera os dados reais da variante carregarem e tenta de novo até lá. Na prática: o botão demora alguns instantes a mais em tema lento, e em troca nunca aparece onde não deve.
O cliente escolhe o tamanho dentro do provador. O adapter seleciona a variação correspondente no formulário do produto, espera o tema recalcular a variante e então aciona o botão de compra nativo.
A escolha por acionar o botão, e não enviar o formulário, é deliberada: há tema que intercepta apenas o clique. Enviando o formulário, esses temas fariam a página navegar para o carrinho e tirariam o cliente de onde ele estava. Acionando o botão, a adição acontece por AJAX e o mini-cart abre no lugar.
O caminho de carrinho é validado em loja Nuvemshop em produção, tanto na página de produto quanto a partir de cards na home e na listagem.
Para conferir na sua loja antes de colar qualquer coisa, existe uma extensão de navegador que injeta o SDK em qualquer site e mostra a detecção de plataforma, o SKU resolvido e o fluxo de carrinho. Dá para validar a integração inteira sem alterar nada no painel.
Não. É uma linha colada em Configurações > Códigos externos > Cabeçalho, no painel da loja. Nenhum aplicativo é instalado e nenhum arquivo de tema é alterado.
Não. O campo de Códigos externos é da própria plataforma e já se aplica a todas as páginas da loja.
Não. O adapter ignora de propósito os dados estruturados da página, que na Nuvemshop costumam descrever os produtos recomendados em vez do produto aberto, e usa apenas o dado real da variante. O efeito prático é que o botão pode levar um instante a mais para aparecer em tema lento.
Pelo SKU textual da variante, o mesmo código que a sua equipe já usa no painel da Nuvemshop. Não há id numérico intermediário.
Não. O app instalado na loja autoriza a leitura do catálogo por OAuth e importa produtos, variantes, preços, imagens e categorias, com webhook avisando quando algo muda.
Não. A Nuvemshop abre a sacola sozinha depois de adicionar, então o provador segue aberto para a avaliação e o cliente retoma a navegação de onde parou.