Adobe Commerce / Magento Open Source 集成#

通过 Magento 模块或自定义主题安装 Room Visualizer，并将展示的简单产品 SKU 映射到 ideal.house 目录。

验证状态： Adobe Commerce 前端文档已于 2026年9月7日审核。无商家安装实例可供测试。Luma/Blank 主题、Hyvä 和 PWA Studio 使用不同的 JavaScript 技术栈；下文具体示例针对标准 RequireJS 网上店铺。

加载 SDK 之前： 打开 Dashboard → Settings，将你的店铺前台来源添加到 Allowed Origins (CORS)，然后点击 Save。包含已发布的域名以及任何预览或暂存环境来源；多个来源用逗号分隔。参见配置步骤。

前提条件与范围#

准备开发实例、自定义模块或子主题、部署访问权限、Shop ID、Publishable Key 和已导入的测试 SKU。切勿修改 vendor/ 或基础主题下的文件。Hyvä 和 PWA Studio 需要各自的 Alpine/React 适配器，不得盲目复制 RequireJS 代码。

最小化 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>

Product Code 是精确导入的 sku，而非 Magento 的数值型实体 ID。

添加产品页面区块#

为 catalog_product_view 创建小型模块或主题布局更新。让区块指向位于产品操作区域附近的 .phtml 模板。该模板可以安全地渲染初始产品 SKU：

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>

对于可配置产品，页面初始 SKU 通常就是父级 SKU。如果 ideal.house 资源属于子简单产品，则初始时将 host 留空，仅在选择简单产品解析之后才填入。

一次性加载 SDK#

在模块或主题中添加本地 RequireJS 初始化器。该初始化器会创建外部脚本并在追加前应用所有必需的数据属性：

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);
  };
});

从模板中以声明方式初始化，遵循 Adobe 推荐的 text/x-magento-init 机制：

html

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

这会生成与最小化契约相同的 SDK 元素，而不会将凭证放入 RequireJS URL 中。网上店铺代码中仅使用 Publishable Key。

选定的可配置 SKU#

标准可配置产品部件通过 Magento 自己的组件暴露选择状态，但主题覆盖会改变其形状。在你的模块中实现一个 RequireJS mixin 或在主题解析简单产品 ID 的位置添加监听器，将该 ID 从服务器提供的 JSON 映射到其 SKU，并替换 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);
}

该 mixin 和 ID 到 SKU 的数据是客户适配器工作。不要从选项标签推断子 SKU，也不要记录不属于公开 SDK 契约的 ideal.house 事件或方法。

动态内容与缓存#

色块变更、AJAX 加载的推荐商品、快速查看或客户特定内容替换其 host 后，重建容器。Magento 的 contentUpdated 事件初始化注入内容中的 Magento 组件；它本身不会提供选定的 SKU，因此你的适配器仍必须解析并渲染正确的代码。

代码变更后，运行适合环境的部署步骤，清除布局/全页/区块缓存，并重新部署静态内容。启用生产打包/压缩和 Varnish/CDN 后进行测试。

导入产品数据#

将简单产品和子产品 SKU 映射到 ideal.house sku。使用商品上传，包括导入、任务状态、列出商品、更新商品、删除商品和重试指南。Magento 导出、Admin API 调用、定时任务和 Webhook 均为客户适配器。

验证与移除#

测试简单产品、可配置产品、缺少 SKU、子产品已禁用和未知 SKU 场景。确认单个 SDK 请求、每次色块/选项变更后精确的 SKU 映射、快速查看和推荐中的清洁行为、移动端布局、缓存命中、客户组页面和同意控制。验证源或静态资源中不出现任何机密凭证。

要移除，请禁用/卸载自定义模块或移除子主题的布局/模板/RequireJS 文件，重新部署静态内容，清除缓存，并验证 SDK URL 和容器已不存在。