Ideal House
Pular para o conteúdo

integração SHOPLINE#

Integre o Room Visualizer a uma loja online SHOPLINE por meio de uma extensão de app de tema ou um bloco de tema personalizado controlado.

Status de verificação: documentação do tema Online Store 2.x/3.0 do SHOPLINE revisada em 7 de setembro de 2026. Nenhum app de parceiro ou loja de teste de comerciante estava disponível. A sintaxe do template e os tipos de extensão suportados variam conforme a geração do Online Store, portanto valide contra a versão exata da loja.

Antes de carregar o SDK: abra Dashboard → Settings, adicione sua origem de loja virtual a Allowed Origins (CORS) e clique em Save. Inclua o hostname publicado e quaisquer origens de preview ou staging que você utilize; separe várias origens com vírgulas. Veja Etapas de configuração.

Escolha uma superfície de integração#

  • Para um app público reutilizável no Online Store 2.0/2.1, o SHOPLINE recomenda uma Theme App Extension com um App Block e um App Embed Block opcional.
  • Os temas Online Store 3.0 fornecem blocos reutilizáveis com ativos JavaScript opcionais e App Blocks.
  • As APIs Script Tag/Asset são legadas ou dependem da versão/tipo de app; não as escolha sem verificar a tabela de compatibilidade do SHOPLINE.
  • Para uma personalização de tema de uma única loja, use a estrutura de bloco/template e de ativos da versão ativa.

Prepare uma loja de desenvolvimento, acesso à extensão/tema, Shop ID, Publishable Key e códigos de variante importados.

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>

O Product Code deve corresponder ao sku do catálogo ideal.house. Esta documentação não afirma que existe um app SHOPLINE do ideal.house instalável.

Construa o bloco do tema#

Crie um App Block ou bloco de tema público que renderize um host nas páginas de detalhe do produto. Use o objeto produto/variante exato e os ajudantes de escape documentados para sua geração do Online Store. O HTML final da loja virtual deve ser:

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

No código-fonte do modelo, substitua CHAIR-OAK-01 pela expressão de código/SKU da variante atualmente selecionada. Não cole uma expressão Shopify Liquid em modelos Handlebars SHOPLINE 3.0; são linguagens e contratos de objeto diferentes.

Para um App Block, adicione-o à seção de produto no Theme Editor. Para um App Embed, use-o para carregar o SDK globalmente sem interface visível. App Blocks normalmente exigem que o comerciante os ative/posicione após a instalação.

Carregue o SDK uma vez#

No ativo JavaScript da extensão/tema, crie o script com as duas configurações públicas antes de anexá-lo:

js
if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
  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);
}

Use a configuração da extensão/parâmetros dinâmicos para credenciais multi-comerciantes. Exponha apenas o Publishable Key; mantenha os segredos do app no seu servidor.

Variantes selecionadas e seções dinâmicas#

Conecte o callback de seleção de produto documentado do tema ativo a este adaptador:

js
function setIdealhouseVariant(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);
}

Os temas SHOPLINE são personalizáveis, portanto este guia não inventa um evento universal de variante da loja virtual. O Online Store 3.0 documenta eventos de seção/bloco do theme editor, mas esses são eventos de ciclo de vida do editor, não de seleção de variante pelo comprador.

Quando seções, filtros, paginação, visualização rápida ou a pré-visualização do theme editor re-renderizarem um nó de produto, crie um contêiner fresco. Limpe os listeners quando um bloco for descarregado no Theme Editor. Botões de cartão de produto precisam de um SKU em nível de item; omita o controle quando uma variante final não for conhecida.

Importar produtos#

Exporte os dados de produto e variante do SHOPLINE e vincule o código selecionado da loja virtual ao sku do catálogo ideal.house. Use Envio de produtos e os guias aprovados para Importação, Status da tarefa, Listagem, Atualizações, Exclusão e Tratamento de novas tentativas.

A sincronização de API Admin do SHOPLINE, webhooks, OAuth de apps e distribuição na app store são trabalho do adaptador do cliente.

Verificar e remover#

Teste a instalação e ativação do bloco pelo comerciante, um produto simples, cada variante, códigos ausentes/desconhecidos, cartões, visualização rápida, filtros, navegação estilo SPA, mobile, consentimento, pré-visualização do theme editor e todas as versões suportadas do Online Store. Confirme uma solicitação de SDK e o mapeamento exato de código/SKU.

Para remover, desative o App Block/Embed e desinstale a extensão, ou remova o bloco e o ativo personalizados. Publique o tema limpo, limpe os caches e verifique se nenhuma URL do SDK nem marcação data-idealhouse-* permanece.

Referências oficiais da plataforma#