Ideal House
Pular para o conteúdo

Integração React / Next.js#

Use o SDK do navegador ideal.house diretamente no React ou Next.js. Não há pacote npm separado de ideal.house React neste guia.

Status de verificação: A marcação do SDK foi verificada contra o modelo atual do Dashboard; a documentação oficial de ciclo de vida/script do React e Next.js foi revisada em 7 de setembro de 2026. Nenhuma aplicação de cliente ou credencial de produção estava disponível, portanto, valide o aplicativo construído de ponta a ponta.

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 limites#

Prepare Shop ID, Publishable Key, um catálogo SKU importado e um valor de produto/variação renderizado pelo cliente. O Publishable Key pode estar presente na marcação do navegador. Mantenha os Client Secrets, chaves AI API e quaisquer credenciais privadas de importação de produto no servidor.

O SDK descobre containers DOM. O React é responsável por quando esses nós são montados; sua integração é responsável por resolver a variante atual e substituir o container quando seu SKU mudar.

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>

data-product-code deve ser igual ao ideal.house catálogo sku exatamente.

Componente React#

Monte um novo container sempre que o código do produto mudar. Um key força o React a substituir o nó DOM em vez de reutilizar um container que o SDK possa já ter populado:

tsx
type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

Passe o SKU da variante selecionada, não um título de produto, slug de rota, ID do banco de dados ou rótulo de opção. Se a seleção estiver incompleta, renderize null.

Carregador do App Router Next.js#

Posicione o SDK uma vez no layout compartilhado mais restrito que cubra as páginas de produto. O Next.js documenta o afterInteractive para scripts que carregam após alguma hidratação:

tsx
import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

Renderize o IdealhouseSdk uma vez a partir de um layout, depois renderize o RoomVisualizerButton dentro de um Componente Cliente que é responsável pela seleção de variantes. Os valores com prefixo NEXT_PUBLIC_ são enviados ao navegador; use-os apenas para Shop ID e Publishable Key.

Para o Pages Router ou React puro, crie o script uma vez no shell HTML, ou use um único efeito de nível superior:

tsx
useEffect(() => {
  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);
}, []);

O modo estrito do React intencionalmente executa um ciclo extra de configuração de desenvolvimento, portanto, a verificação de duplicata é necessária. Não remova a tag compartilhada do SDK quando um componente de produto individual for desmontado.

As mudanças de rota no lado do cliente não recarregam o script do layout. Utilize como chave cada controle de produto pela identidade estável da rota mais SKU se o mesmo SKU puder aparecer em várias visualizações montadas simultaneamente. Para grids, cada card precisa do seu próprio SKU. Quando a rolagem infinita adiciona cards, o React monta naturalmente novos containers limpos.

Para seleção de variante, derive o selectedVariant.sku do seu estado de comércio e passe-o como productCode. Não chame um método de atualização de SDK não documentado. Gavetas de visualização rápida e transições de rota devem desmontar seu componente anterior para que o DOM processado não vaze para o próximo produto.

Se a hidratação do React relatar uma inconsistência, garanta que o servidor e o primeiro render do cliente estejam de acordo. É válido renderizar nenhum container até que o estado de comércio do cliente tenha resolvido o SKU.

Importar dados de produto#

Mapeie o SKU canônico da variante do backend de comércio para ideal.house sku. Use Upload de produto e consulte importar produtos, Status da tarefa, listar produtos, atualizar produtos, excluir produto e Erros e novas tentativas.

Qualquer consulta ao catálogo do backend, webhook, sincronização agendada ou serviço de token de lançamento permanece como código de aplicação; o SDK do navegador não o fornece.

Verificar e remover#

Teste renderização no servidor/hidratação, carregamento rígido, navegação do cliente, botão Voltar/Avançar do navegador, mudanças de variante, SKUs nulos/desconhecidos, cards repetidos, visualização rápida, estados Suspense/carregamento, mobile, controles de consentimento e uma build de produção. Confirme uma única solicitação de SDK e igualdade exata do DOM Product Code/SKU. Inspecione os bundles do cliente construídos quanto a segredos acidentais.

Para remover, exclua o componente/tag compartilhado do SDK e todos os usos de RoomVisualizerButton, remova as duas variáveis de ambiente públicas, faça build novamente e verifique se nenhuma marcação de SDK URL ou data-idealhouse-* permanece.

Referências oficiais do framework#