OpenCart 集成#

通过 OpenCart 4 扩展或自定义主题添加 Room Visualizer，并将稳定的店铺前台产品 code 映射到 ideal.house 目录。

验证状态： OpenCart 4 扩展文档已于 2026年9月7日 审核完毕，无测试店铺可供测试。OpenCart 3 和第三方主题使用不同的路径和事件约定；请将本指南适配到已安装的主版本。

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

前置条件与 code 选择#

准备暂存店铺、扩展/主题开发访问权限、Shop ID、Publishable Key 以及已导入的测试记录。OpenCart 核心通常在产品模板中暴露 model，而 SKU 可能需要根据版本和主题进行控制器/扩展工作。选择一个值并一致地将其作为 ideal.house sku 使用。

不要直接编辑核心目录文件。将更改打包为 OpenCart 4 扩展，或保留在版本控制的自定义主题中。

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

Product Code 必须与导入的 ideal.house sku 逐字符相等。

渲染产品容器#

通过扩展扩展活跃的产品模板。如果您特意将 OpenCart model 字段映射为 ideal.house sku，请在产品操作附近放置：

{% if model %}
  <div class="idealhouse-host">
    <div
      data-idealhouse-button-container
      data-product-code="{{ model }}">
    </div>
  </div>
{% endif %}

Twig 自动转义取决于环境配置；确保所选值为 HTML 属性转义。如果选择实际的 SKU 字段，请将该清理后的值添加到扩展中的控制器模板数据中，并渲染它以替代 model。

加载 SDK 一次#

通过扩展/主题机制添加店铺前台 JavaScript 资源。它应创建一个带有必需属性的脚本：

if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
  const 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.append(script);
}

将两个公开值存储在扩展配置中并安全渲染。永远不要将 ideal.house Client Secret 放入 JavaScript、Twig、扩展日志或缓存 HTML 中。

选项、变体与动态渲染#

OpenCart 选项并不总是与 SKU 变体一一映射。如果您的商店使用 option/variant 扩展，请通过该扩展的文档化 resolved-variant 回调和数据模型进行集成。仅当其提供精确的选中 code 时才替换 host：

function renderIdealhouseCode(host, productCode) {
  host.replaceChildren();
  const code = String(productCode || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

这是客户适配器代码；本指南中没有通用的 OpenCart variant 事件。对于 AJAX 搜索、分类过滤器、弹窗和快速查看，在扩展的模板中渲染干净的容器，或从其文档化的完成回调中调用桥接。请勿复制由 SDK 生成的子节点。

导入产品#

导出每个可可视化项所选的 OpenCart model/SKU，并将其映射到 ideal.house sku。使用 商品上传，然后遵循 导入商品、任务状态、列出商品、更新商品、删除商品 以及 错误与重试。

OpenCart Admin API 调用、定时导出、事件监听器和 webhook 属于客户自有的集成工作。

验证与移除#

测试简单产品、每个支持的选项组合、缺失和重复的 code、未知 ideal.house SKU、分类/搜索页面、快速查看、浏览器后退/前进、移动端布局、多商店、语言/货币、同意设置以及生产缓存/压缩。确认恰好一次 SDK 请求以及精确的 code 匹配。

要移除，请停用/卸载扩展或移除自定义主题覆盖和资源，刷新 OpenCart 修改/事件，清除主题/CDN 缓存，并确认 SDK 请求和容器均已消失。

官方平台参考#

• OpenCart 4：扩展
• OpenCart 4：事件
• OpenCart 文档