Integração Adobe Commerce / Magento Open Source#

Instale Room Visualizer por meio de um módulo Magento ou tema personalizado e mapeie o produto simples exibido SKU para o catálogo ideal.house.

Status de verificação: documentação frontend do Adobe Commerce revisada em 7 de setembro de 2026. Nenhuma instalação de comerciante estava disponível. Temas Luma/Blank, Hyvä e PWA Studio usam pilhas de JavaScript diferentes; o exemplo concreto abaixo foca na loja padrão com RequireJS.

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.

Pré-requisitos e escopo#

Prepare uma instância de desenvolvimento, um módulo personalizado ou child theme, acesso de deploy, a Shop ID, a Publishable Key e SKUs de teste importados. Nunca modifique arquivos sob vendor/ ou um tema base. Hyvä e PWA Studio exigem seu próprio adaptador Alpine/React e não devem copiar código RequireJS cegamente.

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 Código do Produto é o sku importado exatamente, não o ID de entidade numérico do Magento.

Adicione um bloco na página de produto#

Crie um pequeno módulo ou atualização de layout do tema para catalog_product_view. Aponte um bloco a um template .phtml posicionado próximo às ações do produto. O template pode renderizar o SKU inicial do produto com segurança:

php

<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

Para um produto configurável, o SKU inicial da página é normalmente o SKU pai. Se os ativos do ideal.house pertencem a produtos simples filhos, deixe o host vazio inicialmente e preenchá-lo apenas após o produto simples selecionado ser resolvido.

Carregue o SDK uma vez#

Adicione um inicializador RequireJS local no seu módulo ou tema. O inicializador cria o script externo e aplica todos os data attributes necessários antes de anexá-lo:

define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    var 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.appendChild(script);
  };
});

Inicialize-o declarativamente a partir do template, seguindo o mecanismo text/x-magento-init recomendado pela Adobe:

html

<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

Isso produz o mesmo elemento do SDK que o contrato mínimo, sem colocar credenciais em uma URL RequireJS. Use somente a Publishable Key no código da loja.

SKU configurável selecionado#

O widget padrão de produto configurável expõe o estado da seleção por meio do próprio componente do Magento, mas sobreposições de tema alteram essa forma. Implemente um mixin RequireJS ou um listener dentro do seu módulo no ponto em que o tema resolve um ID de produto simples, mapeie esse ID ao seu SKU a partir do JSON fornecido pelo servidor e substitua o host:

function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

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

Esse mixin e os dados de ID-para-SKU são trabalho do adaptador do cliente. Não infira o SKU filho a partir de rótulos de opção e não documente um evento ou método do ideal.house que não faça parte do contrato público do SDK.

Conteúdo dinâmico e caches#

Recrie o container após alterações de swatch, recomendações carregadas via AJAX, visualização rápida ou conteúdo específico do cliente substituírem o host. O evento contentUpdated do Magento inicializa componentes do Magento em conteúdo injetado; ele por si só não fornece um SKU selecionado, portanto seu adaptador ainda precisa resolver e renderizar o código correto.

Após alterações de código, execute as etapas de deploy apropriadas ao ambiente, limpe caches de layout/página inteira/blocos e redeploy o conteúdo estático. Teste com bundling/minificação de produção e Varnish/CDN habilitados.

Importação de dados de produto#

Mapeie SKUs de produtos simples e filhos para ideal.house sku. Use Upload de produto, incluindo importar, status do trabalho, listagem, atualizações, exclusão e orientação de nova tentativa. Exportações de Magento, chamadas de API do Admin, trabalhos cron e webhooks são adaptadores do cliente.

Verificação e remoção#

Teste casos de produto simples, configurável, SKU ausente, filho desabilitado e SKU desconhecido. Confirme uma única requisição do SDK, mapeamento exato de SKU após cada alteração de swatch/opção, comportamento limpo na visualização rápida e recomendações, layout mobile, hits de cache, páginas de grupo de clientes e controles de consentimento. Verifique que nenhuma credencial secreta apareça no source ou nos assets estáticos.

Para remover, desative/desinstale o módulo personalizado ou remova os arquivos de layout/template/RequireJS do child-theme, redeploy o conteúdo estático, limpe caches e verifique que a URL do SDK e os containers estejam ausentes.