Ideal House
Pular para o conteúdo

integração Ecwid#

Use um aplicativo de loja personalizada Ecwid e o ciclo de vida documentado do API JS da loja para adicionar controles Room Visualizer às páginas de produtos Ecwid.

Status de verificação: Documentação do Ecwid Storefront JS API revisada em 7 de setembro de 2026. Nenhum aplicativo Ecwid ou loja de teste de comerciante estava disponível. Os campos exatos do payload da página devem ser confirmados contra a referência atual OnPageLoaded antes da implantação.

Antes de carregar o SDK: Abra Dashboard → Configurações, adicione a origem da sua loja ao campo Allowed Origins (CORS) e clique em Salvar. Inclua o nome de host publicado e quaisquer origens de preview ou staging que você usar; separe várias origens com vírgulas. Veja etapas de configuração.

Pré-requisitos e caminho suportado#

Ecwid requer um aplicativo personalizado com um arquivo JavaScript auto-hospedado para personalização duradoura da loja. Prepare uma loja/aplicativo de desenvolvimento Ecwid, um arquivo adaptador hospedado em HTTPS, Shop ID, Publishable Key e SKUs de produto/variação importados.

Se o Ecwid estiver embutido em outro CMS, o aplicativo de loja personalizada permanece o local confiável para o código, pois ele é executado junto com a loja Ecwid. Um script da página pai pode não compartilhar o mesmo ciclo de vida ou documento em todos os modos de incorporação.

Contrato mínimo do SDK#

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>

Use o Ecwid SKU exato que você importou como ideal.house sku.

Inicialize seu aplicativo de loja Ecwid#

Siga o início rápido de loja personalizada do Ecwid para registrar o arquivo auto-hospedado. Inicie-o com o callback documentado pronto para API e, em seguida, carregue o ideal.house SDK uma vez:

js
Ecwid.OnAPILoaded.add(function () {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

  const script = document.createElement('script');
  script.src = 'https://sdk.ideal.house/sdk.js';
  script.async = true;
  script.dataset.shopId = '<SHOP_ID>';
  script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
  document.head.append(script);
});

Para um aplicativo multi-loja, obtenha os dois valores públicos ideal.house da configuração pública segura do seu aplicativo. Nunca coloque um segredo de aplicativo Ecwid, token de acesso ou ideal.house Client Secret neste arquivo.

Renderizar nas páginas de produto#

Ecwid documenta Ecwid.OnPageLoaded.add() e fornece informações da página para seu callback. Use a referência API atual para confirmar o tipo e o identificador da página de produto, busque ou leia os dados do produto por meio da interface de cliente suportada do Ecwid e, em seguida, passe o SKU resolvido para:

js
function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

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

Insira o host em um local estável de detalhes do produto após o Ecwid concluir o render da página. Remova o host anterior quando o tipo de página mudar. O seletor DOM e a pesquisa de payload-da-página-para-produto são código do adaptador do cliente, pois os layouts e as versões de payload da loja Ecwid podem mudar.

Opções e navegação#

Quando um comprador escolhe opções de produto, aguarde até que o Ecwid resolva a variação comprável e seu SKU. Chame o mountIdealhouse() com esse SKU ou limpe o host se a seleção estiver incompleta. Não concatene rótulos de opção para fabricar um código.

Ecwid é uma loja de página única. Use seu ciclo de vida documentado de páginas (callbacks de OnPageLoaded/troca de página) em vez de ouvir apenas o DOMContentLoaded do navegador. A navegação por categoria/pesquisa, o botão Voltar/Avançar do navegador, widgets incorporados e popups de produto devem remover os hosts de produto obsoletos e montar um novo container após o render.

Importar produtos#

Exporte os campos Ecwid de produto e variação SKU e os mapeie para ideal.house sku. Use Upload de produto, incluindo importar produtos, Status da tarefa, listar produtos, atualizar produtos, excluir produto e Erros e novas tentativas.

Qualquer exportação Ecwid REST API, webhook, instalação OAuth ou sincronização recorrente é de propriedade do cliente e deve ser implementada no lado do servidor com a autorização Ecwid apropriada.

Verificar e remover#

Teste a instalação do aplicativo, inicialização do API, transições de produto/categoria/pesquisa, cada variação, SKUs ausentes e desconhecidos, botão Voltar/Avançar do navegador, um widget Ecwid incorporado em outro site, layout mobile, consentimento e clientes logados/deslogados. Confirme uma solicitação de SDK no documento contendo o host e igualdade exata de SKU.

Para remover, desvincule o arquivo JavaScript auto-hospedado do aplicativo personalizado ou desinstale o aplicativo, remova os hosts/listeners injetados e verifique se o SDK URL e todos os nós data-idealhouse-* desaparecem após a navegação na loja e uma atualização rígida.

Referências oficiais da plataforma#