Ideal House
Pular para o conteúdo

Integração WordPress#

Adicione o ideal.house Room Visualizer a um site WordPress carregando um único script público de navegador e renderizando um container cujo código do produto corresponda ao SKU do catálogo importado.

Status de verificação: Documentação revisada em 7 de setembro de 2026. Este guia não foi certificado de ponta a ponta contra um tema WordPress de cliente. Valide-o em uma cópia de staging do seu tema e versões de page-builder antes de publicar.

Antes de carregar o SDK: Abra Dashboard → Settings, adicione a origem da sua storefront ao Allowed Origins (CORS) e clique em Save. Inclua o hostname publicado e quaisquer origens de preview ou staging que você use; separe múltiplas origens com vírgulas. Veja Etapas de configuração.

Escopo e pré-requisitos#

Este guia cobre sites de conteúdo WordPress, temas clássicos, temas de blocos e page builders que permitem adicionar HTML. Se o site usar dados de produto WooCommerce, use o guia WooCommerce para seleção de variant.

Preparação:

  • acesso de administrador e, para o método duradouro, um tema filho ou pequeno plugin específico do site;
  • o Shop ID e Publishable Key do Dashboard ideal.house;
  • um produto já importado para o ideal.house com um sku conhecido;
  • uma página de staging onde cache/minificação possa ser desabilitada durante os testes.

A Publishable Key é destinada a markup de navegador. Nunca coloque uma chave Client Secret ou AI API em WordPress HTML.

Confirme o contrato do SDK#

A instalação suportada mínima consiste exatamente em um script SDK e um container de botão gerado:

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 sku do catálogo, incluindo maiúsculas/minúsculas e pontuação. O SDK é responsável pelo conteúdo do container. O WordPress não fornece um plugin ideal.house neste guia.

Instalar o script em todo o site#

O WordPress recomenda carregar scripts front-end via wp_enqueue_script(). Adicione o seguinte a um functions.php de child theme ou a um plugin específico do site. O filter adiciona os dois atributos data necessários à tag que o WordPress produz.

php
add_action('wp_enqueue_scripts', function () {
    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);

Substitua ambos os placeholders. Versões do WordPress anteriores ao 6.3 não aceitam a forma de array do último argumento wp_enqueue_script(); passe true e use o filter script_loader_tag para adicionar async também.

Não reinstale o SDK em um bloco Code ou tag manager. No DevTools, document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length deve retornar 1.

Posicionar um botão#

No block editor, adicione um bloco Custom HTML onde o botão deve aparecer:

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

Para cards repetidos, renderize o mesmo markup a partir do template do theme e escape o código como um atributo HTML:

php
<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

Seu tema ou plugin deve fornecer $idealhouse_product_code. Não use um ID de publicação, slug ou título a menos que esse valor exato seja também o sku ideal.house importado.

Mapeamento de produto e variante#

Crie uma tabela de mapeamento explícita antes do lançamento:

valor WordPressvalor ideal.houseRegra
campo personalizado como idealhouse_skuskucorrespondência exata de string
uma página sem variantesum produto importadoum contêiner
item de coleção do page-buildercampo SKU em nível de itemnunca reutilize um código em toda a coleção

Se a página mudar entre variants, o adapter do cliente deve definir o novo data-product-code. Limpe o container antigo antes de inserir o novo para que o estado obsoleto do viewer não possa ser reutilizado:

js
function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

Este é código do adapter do cliente. Ele não chama um método ideal.house não documentado nem inventa um evento WordPress; chame-o a partir do callback documentado fornecido pelo seu theme ou page builder.

Para filtros AJAX, rolagem infinita, cartões de produto em janelas modais ou transições do construtor de páginas, insira um novo contêiner depois que o novo nó do produto estiver no DOM. Não clone um contêiner que o SDK já preencheu. Se sua ferramenta não expuser uma função de retorno estável para a renderização, adicione o contêiner ao modelo do item para que cada renderização crie marcação limpa.

Após uma edição no theme, purge os caches do WordPress, CDN e de plugins de otimização. Exclua https://sdk.ideal.house/sdk.js da reescrita de delay/defer se um plugin de performance remover seus atributos data ou adiá-lo até após a interação.

O conteúdo WordPress não é sincronizado automaticamente. Exporte o campo personalizado escolhido como sku e importe os registros correspondentes via Envio de produtos. Continue com Importar produtos, Status da tarefa, Listar produtos, Atualizar produtos, Excluir produto e Erros e novas tentativas.

Verificar antes de publicar#

  1. Abra o staging em uma janela de navegador privativo, não na prévia do editor WordPress.
  2. Confirme que a requisição do SDK retorna com sucesso e apenas uma vez.
  3. Inspeccione o container e compare o data-product-code caractere por caractere com o sku importado.
  4. Confirme que um SKU importado produz um controle do visualizer utilizável e que um SKU desconhecido não expõe um controle quebrado.
  5. Teste a navegação do construtor de páginas, filtros, Back/Forward do navegador, layout móvel e configurações de consentimento.
  6. Selecione cada variant suportado e confirme que o container é recriado com seu SKU.
  7. Verifique o console do navegador e teste novamente com cache/minificação habilitados.

Remover a integração#

Remova a função enqueue e o filter script_loader_tag, depois apague todos os blocos data-idealhouse-button-container ou fragmentos de template. Purge todos os caches e verifique se a URL SDK está ausente do page source e do Network panel.

Referências oficiais da plataforma#