Ideal House
Pular para o conteúdo

Integração WooCommerce#

Adicione botões do Room Visualizer às páginas de produtos do WooCommerce e mantenha o código do produto ideal.house sincronizado com o código da variação selecionada SKU.

Status de verificação: Documentação e comportamento público do WooCommerce revistos em 7 de setembro de 2026. Esta implementação não foi certificada em uma loja de cliente. Modelos clássicos, temas de blocos, extensões de variação e plugins de visualização rápida podem renderizar DOM diferentes; teste a pilha exata em homologação.

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.

Escopo e pré-requisitos#

Este guia tem como alvo WooCommerce no WordPress. Ele usa um plugin específico do site ou tema filho pequeno, o carregador padrão de ativos do WordPress e ganchos de produto do WooCommerce. Não é um plugin WordPress ideal.house instalável.

Prepare acesso de administrador e de arquivos, Shop ID, Publishable Key e registros ideal.house importados para cada SKU visualizável. Forneça a cada produto simples e a cada variação suportada um SKU não vazio e único no WooCommerce.

Marcação SDK mínima#

Este é o contrato público do SDK usado pela integração:

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 container gerado deve corresponder ao sku do catálogo importado. Não coloque IDs do banco de dados do WooCommerce em data-product-code a menos que você tenha usado deliberadamente esses IDs como SKUs de catálogo.

Carregue o SDK uma vez#

Adicione este código ao functions.php de um tema filho ou a um plugin específico do site. Substitua os espaços reservados.

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') return $tag;

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

Se você oferecer suporte a versões do WooCommerce no WordPress anteriores ao 6.3, passe true como último argumento de enqueue e adicione async no filtro.

Renderize o host da página de produto#

O gancho a seguir posiciona um host após o formulário de adicionar ao carrinho. Produtos simples recebem seu SKU imediatamente. Produtos variáveis começam vazios; o adaptador do navegador os preenche quando uma variação completa é selecionada.

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

Confirme se o gancho existe no seu modelo de produto. Um tema que substitui o modelo WooCommerce ou o bloco de Coleção de Produtos pode exigir uma integração de bloco ou outro gancho WooCommerce documentado.

Sincronize uma variação selecionada#

O formulário de variação embutido do WooCommerce dispara eventos do ciclo de vida do jQuery de variação. Adicione um arquivo local, por exemplo assets/js/idealhouse-woocommerce.js, faça seu enqueue com dependências jquery e wc-add-to-cart-variation e use:

js
(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

Este arquivo é um adaptador WooCommerce de propriedade do cliente. Se um plugin de variação substituir o script padrão do formulário, use o callback de seleção documentado desse plugin em vez de pressupor que esses eventos ainda são disparados. Não atualize apenas o atributo de um container já processado pelo SDK; substitua-o por um container limpo.

Grades de produtos, visualização rápida e navegação AJAX#

Para cartões de catálogo, use um gancho de loop de produto como woocommerce_after_shop_loop_item e renderize o SKU do produto simples. Produtos variáveis em uma grade geralmente não têm uma variação resolvida; vincule à página do produto ou crie um adaptador explícito de seleção de variação.

Plugins de visualização rápida e Blocos WooCommerce podem injetar produtos após o carregamento inicial da página. Coloque o host no modelo que eles renderizam e execute seu bridge render() a partir do callback de conclusão documentado dessa ferramenta. Se não houver um callback estável, um MutationObserver escopado pode detectar novos nós .idealhouse-host, mas o cliente é responsável por seu desempenho e ciclo de vida.

Mapeie WC_Product::get_sku() e cada WC_Product_Variation::get_sku() para ideal.house sku. Produtos pai e filho não devem compartilhar um código se representarem ativos visuais diferentes.

WooCommerce não empurra automaticamente alterações do catálogo para ideal.house. Use Upload de produto e seus guias para importação, status do trabalho, listagem, atualizações, exclusão e tratamento de nova tentativa. Qualquer exportação agendada ou bridge de webhook é implementação do cliente.

Verifique antes do lançamento#

  1. Teste um produto simples, um produto variável, um SKU ausente e um SKU ausente do ideal.house.
  2. Confirme que o SDK é solicitado uma vez e que sua tag de script mantém ambos os atributos de credencial.
  3. Selecione todas as variações e verifique se data-product-code é igual ao SKU da variação.
  4. Redefina o formulário de variação; o container antigo deve desaparecer.
  5. Teste uma grade de produtos, visualização rápida, filtros AJAX, fragmentos de carrinho, botão de adicionar ao carrinho fixo no mobile e Back/Forward do navegador, quando aplicável.
  6. Teste enquanto estiver desconectado, com controles de consentimento e cache de produção habilitados.
  7. Verifique se nenhum Client Secret aparece em HTML, JavaScript, logs ou mapas de origem.

Remover a integração#

Remova os ganchos/filtro PHP e o enqueue do adaptador local de variação. Exclua hosts dos modelos ou blocos substituídos, limpe transientes do WooCommerce e caches de página/CDN e, em seguida, confirme se nenhuma solicitação de SDK ou elemento data-idealhouse-* permanece.

Referências oficiais da plataforma#