Integração Wix#

Integre o Room Visualizer ao Wix Stores pelo mecanismo de extensão do Wix adequado ao tipo do seu site. Wix Editor e Wix Studio exigem abordagens diferentes.

Status de verificação: Documentação de extensão do Wix revisada em 7 de setembro de 2026. Nenhuma credencial de site ou app de cliente Wix estava disponível, portanto esta não é certificada de ponta a ponta. O SDK deve compartilhar o DOM da vitrine com seu container; um iframe HTML não é um substituto.

Antes de carregar o SDK: Abra Dashboard → Configurações, adicione a origem da sua vitrine a Allowed Origins (CORS) e clique em Salvar. Inclua o hostname publicado e quaisquer origens de visualização ou homologação que você use; separe várias origens com vírgulas. Consulte etapas de configuração.

Escolha o caminho Wix correto#

Vitrine	Caminho de inserção recomendado	Limitação
Site Wix Editor, um comerciante	Código personalizado do site mais um elemento na página de produto ou app personalizado	Os dados da página ainda precisam de uma integração implementada pelo cliente
App Wix para lojas Wix Editor	Extensão de script incorporado e pontos de inserção do Wix Stores	Os scripts incorporados do Wix Stores não oferecem suporte ao Wix Studio
Site Wix Studio	Slot de plugin de site do Wix Stores	Requer um projeto de app/extensão Wix
Loja Wix headless	Adicione o SDK no seu próprio frontend React/Vue	Siga o guia do framework correspondente

O Wix informa que os scripts incorporados do Stores não estão disponíveis no Wix Studio e orienta os apps a usar uma extensão de plugin de site. Não instale uma solução de script incorporado para o Editor e afirme que ela oferece suporte ao Studio.

Pré-requisitos#

Prepare um site de teste Wix com Wix Stores, permissão para publicar código personalizado ou uma extensão de app, Shop ID e Publishable Key do ideal.house e um SKU de teste importado. Determine se a variante Wix selecionada tem seu próprio SKU. Mantenha todos os segredos do app e as chaves de API do backend fora da página do navegador.

Marcação SDK mínima#

Onde o Wix permite que seu código seja executado no documento da loja virtual, a marcação compatível com ideal.house é:

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

O Código do produto deve corresponder exatamente ao ideal.house sku importado.

Wix Editor: instalar em um site#

No painel do Wix, adicione a tag do SDK em Configurações → Código personalizado, coloque-a no corpo ou no final do corpo da página e selecione as páginas de produto que precisam dela. Publique o site; o modo de pré-visualização não é suficiente para verificar o ambiente de produção.

Em seguida, adicione um elemento personalizado de página de produto ou um ponto de extensão do Wix Stores que produza o container no mesmo documento de nível superior. Evite o Wix HTML Embed para o botão: ele é executado dentro de um iframe, portanto um script no documento pai não consegue descobrir seu container e um script no iframe não consegue controlar a página de produto.

O elemento colocável deve expor uma operação no seu próprio código:

function setIdealhouseSku(host, sku) {
  host.replaceChildren();
  const code = typeof sku === 'string' ? sku.trim() : '';
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Chame-a somente após o Wix fornecer os dados completos do produto ou variante atual pela API disponível para sua página ou extensão. Este é um adaptador implementado pelo cliente; ele deliberadamente não indica um evento de página Wix que não tenha sido verificado.

App Wix: script incorporado para lojas Wix Editor#

O Wix Stores fornece os pontos de inserção details-placeholder e bottom-placeholder para extensões de script incorporado. Acrescente um contêiner externo a um desses pontos; não substitua seu conteúdo, pois outros apps podem compartilhá-lo. Configure o script do SDK como um fragmento incorporado separado ou crie-o programaticamente com os atributos exatos src, data-shop-id e data-publishable-key.

A API de site do Wix, disponível para scripts incorporados criados pela CLI, pode ler o contexto da loja virtual. Obtenha o SKU da variante atual pela API compatível do Stores fornecida pelo Wix e chame sua função de integração setIdealhouseSku(). Mantenha o ponto de inserção vazio até que um SKU completo esteja disponível.

Wix Studio: plugin de site#

Crie um plugin de site do Wix Stores para um ponto de inserção documentado na página de produto. Renderize o contêiner na interface do plugin e carregue o SDK no documento do site renderizado pelo Wix. O plugin deve passar o SKU determinado para a variante atual ao contêiner no DOM. Os nomes dos pontos de inserção e as APIs de componentes do Wix Studio podem mudar; escolha-os na referência atual da CLI/API ao gerar a extensão, em vez de copiar um nome deste guia.

Não use um slot de plugin que renderize o controle dentro de um iframe isolado: o SDK e seu visualizador não foram certificados para essa fronteira. Escolha um ponto de extensão Wix que coloque o container no documento da vitrine, ou use uma loja virtual headless onde você controla o documento.

Mapeamento de produtos e navegação#

Mapeie o sku do produto ou variante do Wix para o sku do ideal.house. Não use silenciosamente o ID do produto Wix como alternativa: um ID gerado não corresponderá ao SKU do catálogo, a menos que você tenha importado esse ID de propósito.

As páginas de produto Wix podem substituir o conteúdo durante a seleção de opções ou a navegação no navegador. Em cada função de retorno documentada para mudança de produto ou seleção:

limpe o container renderizado anteriormente;
resolva a variante selecionada completa;
insira um container novo com seu SKU;
mantenha o host vazio quando não existir um SKU completo ou passível de visualização.

Para galerias e repetidores, cada item precisa de seu próprio SKU em nível de item. Produtos de visualização rápida e modal exigem o mesmo bridge de ciclo de vida na slot do modal.

Importar produtos#

O Wix Stores não sincroniza automaticamente com o ideal.house. Exporte os campos de produto e variante do Wix, defina cada Wix SKU desejado como sku e use Envio de produtos. Consulte Importar produtos, Status da tarefa, Listar produtos, Atualizar produtos, Excluir produto e Erros e novas tentativas.

A sincronização automatizada do Wix com ideal.house, o fluxo de instalação de apps e o processamento de webhooks do Wix são implementações de responsabilidade do cliente; este guia não promete soluções prontas para essas tarefas.

Verifique antes de publicar#

Teste o site publicado em uma janela de navegação privativa no desktop e no mobile.
Confirme que o SDK é carregado uma única vez no mesmo documento que o container.
Compare o Código do produto do DOM com o SKU importado exatamente.
Altere todas as opções até que uma variante final seja selecionada; confirme se o container antigo é removido e um novo aparece.
Teste a navegação do Wix no navegador, as páginas de galeria e listas repetidas de produtos, a visualização rápida, os botões Voltar/Avançar do navegador, as configurações de consentimento e os modos com e sem login.
Confirme que um SKU desconhecido ou vazio não deixa controle do visualizador quebrado.
Para um app, teste instalação, ativação, desativação e desinstalação em sites de teste separados do Wix Editor e Studio, conforme o suporte oferecido.

Remover a integração#

Exclua ou desative a entrada de código personalizado do Wix e remova o elemento da página de produto. Para um app, remova a extensão de script incorporado ou de plugin de site e desinstale o app do site de teste. Publique e confirme que a solicitação do script e todos os nós data-idealhouse-* desapareceram.