Integração BigCommerce#
Adicione Room Visualizer a uma loja Stencil do BigCommerce carregando o SDK uma vez e renderizando o produto ou variante SKU atual em um contêiner de botão gerado.
Status de verificação: documentação de desenvolvedor do BigCommerce revisada em 7 de setembro de 2026. Nenhuma loja de teste estava disponível. Stencil e Catalyst possuem modelos de renderização e navegação diferentes; este guia fornece um caminho acionável para Stencil e direciona lojas Catalyst para um adaptador de framework.
Antes de carregar o SDK: abra Dashboard → Settings, adicione a origem da sua loja ao Allowed Origins (CORS) e clique em Save. Inclua o hostname publicado e quaisquer origens de pré-visualização ou staging que você utilize; separe múltiplas origens por vírgulas. Consulte as etapas de configuração.
Escolha o caminho da loja#
- Stencil: instale o carregador com o Script Manager ou a API de Scripts e adicione o container em um template de tema personalizado.
- Catalyst: adicione o script e o componente no app React/Next.js do Catalyst; siga o guia de React/Next.js.
- Blueprint legado: migre para uma loja compatível ou peça a um desenvolvedor BigCommerce que identifique um ponto de inserção seguro. A documentação atual da API de Scripts trata o Blueprint separadamente.
Você precisa de acesso para edição de tema, um tema/canal de staging, a Shop ID e a Publishable Key do ideal.house, além de pelo menos um SKU BigCommerce importado para o ideal.house.
Contrato mínimo do SDK#
<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 do contêiner deve corresponder exatamente ao catálogo importado sku. Este guia não pressupõe um aplicativo ideal.house BigCommerce.
Instalação no Stencil#
Em Storefront → Script Manager, crie um script de rodapé para os canais e páginas de produto relevantes. Cole apenas a tag de script do SDK do exemplo, com suas credenciais seguras para navegador. O Script Manager é o equivalente ao painel de controle da API de Scripts orientada a canais.
Para um app reutilizável, use a API de Scripts do BigCommerce. Essa operação de API e o fluxo de OAuth do app são de responsabilidade do seu serviço de integração; não exponha seu token de acesso no código da loja.
Confirme que exista apenas uma tag do SDK. Não a inclua também em templates/layout/base.html.
Renderização do produto inicial#
Em um tema Stencil personalizado, adicione o container próximo ao formulário do produto na parcial de visualização de produto usada pelo seu tema:
{{#if product.sku}}
<div
data-idealhouse-button-container
data-product-code="{{product.sku}}"
></div>
{{/if}}
A parcial exata varia conforme o tema. Use o Stencil CLI para visualizar o tema personalizado e mantenha a alteração em um tema com controle de versão em vez de editar o HTML gerado pela loja.
Para cards, renderize o container somente quando o contexto do card expuser o SKU exato que você importou. Um produto com opções pode não ter um SKU de variante final em uma página de categoria; vincule à página do produto, a menos que o comprador tenha selecionado uma variante completa.
Sincronização das opções do produto#
O JavaScript do tema Stencil recebe alterações nas opções do produto por meio do código de product-details específico do tema. Adicione um adaptador do cliente no ponto em que o tema atual tiver resolvido a resposta da variante final:
export function replaceIdealhouseContainer(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);
}
Passe o SKU da variante resolvida a partir do callback do seu tema. Temas BigCommerce podem personalizar ou substituir a implementação padrão de product-details, portanto este guia não inventa um evento global de alteração de opção. Remova o container antigo antes de inserir o novo.
Visualização rápida e páginas dinâmicas#
Quick View, busca facetada, paginação e navegação client-side podem substituir o DOM do produto. Adicione um container limpo em todos os templates renderizados e invoque o mesmo bridge após o callback de renderização documentado pelo tema. Não clone um container já populado pelo SDK.
O Catalyst usa renderização React client-side e não possui contexto Handlebars do Stencil. Carregue o SDK uma vez no shell do app e use o SKU da variante selecionada como chave do componente do visualizador, conforme mostrado no guia de React/Next.js.
Importação e mapeamento de dados de produto#
Mapeie valores de BigCommerce sku para ideal.house sku; para variantes, use cada variante SKU em vez do ID do produto pai. Os dados do catálogo BigCommerce não são sincronizados pelo navegador SDK.
Use Envio de produtos para o contrato de importação aprovado, e depois verifique importar produtos, status do trabalho, listar produtos, atualizar produtos, excluir produto e Erros e novas tentativas. Qualquer exportação, webhook ou sincronização agendada da API BigCommerce é um adaptador operado pelo cliente.
Verificação e remoção#
Antes do lançamento, teste um produto simples, todas as combinações de opções, um produto sem SKU e um SKU ausente do catálogo do ideal.house. Verifique a página do produto, cards de categoria, Quick View, navegação facetada, Back/Forward do navegador, layout mobile, comportamento de consentimento e cada canal ativo da loja. No DevTools, confirme uma requisição bem-sucedida do SDK e uma correspondência exata entre Product Code e SKU.
Para remover a integração, exclua a entrada do Script Manager ou o registro da API de Scripts, remova toda a marcação do container no tema e o código do adaptador, publique o tema limpo e purgue os caches da loja/CDN. Confirme que a requisição do SDK está ausente em todos os canais.