Ideal House
跳转到主要内容

Ecwid 集成#

使用 Ecwid 自定义店铺前台应用和已记录的 Storefront JS API 生命周期，向 Ecwid 商品页添加 Room Visualizer 控件。

验证状态： Ecwid Storefront JS API 文档已于 2026年9月7日 审核。无 Ecwid 应用或商家测试店铺可用。确切的页面 payload 字段必须在部署前对照当前 OnPageLoaded 引用确认。

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

前置条件与支持的方案#

Ecwid 需要一个带有自托管 JavaScript 文件的自定义应用以实现持久的店铺前台定制。准备一个 Ecwid 开发店铺/应用、一个由 HTTPS 托管的适配器文件、Shop ID、Publishable Key，以及已导入的商品/变体 SKU。

如果 Ecwid 嵌入到其他 CMS，自定义店铺前台应用仍是可靠位置，因为它与 Ecwid 店铺前台一起运行。父页面脚本未必在所有嵌入模式下共享相同生命周期或文档。

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

使用你导入为 ideal.house sku 的精确 Ecwid SKU。

初始化你的 Ecwid 店铺前台应用#

遵循 Ecwid 的自定义店铺前台快速入门，注册自托管文件。使用已记录的 API 就绪回调启动它，然后加载一次 ideal.house SDK：

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

  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 值。切勿将 Ecwid 应用密钥、access token 或 ideal.house Client Secret 放入此文件。

在商品页渲染#

Ecwid 记录了 Ecwid.OnPageLoaded.add() 并向其回调提供页面信息。使用当前 API 引用确认商品页类型和标识符，通过 Ecwid 支持的客户端接口获取或读取商品数据，然后将已解析的 SKU 传递给：

js
function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

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

在 Ecwid 完成页面渲染后，将 host 插入稳定的商品详情位置。当页面类型变化时移除先前的 host。DOM 选择器和页面 payload 到商品的查找是客户适配器代码，因为 Ecwid 店铺前台布局和 payload 版本可能变化。

选项与导航#

当购物者选择商品选项时，等待 Ecwid 解析可购买的变体及其 SKU。用该 SKU 调用 mountIdealhouse()，或在选择不完整时清空 host。不要拼接选项标签来伪造编码。

Ecwid 是一个单页店铺前台。使用其已记录的页面生命周期（OnPageLoaded/page-switch 回调），而不是仅监听浏览器 DOMContentLoaded。分类/搜索导航、浏览器 Back/Forward、嵌入组件和商品弹窗必须在渲染后移除陈旧的商品 host 并挂载新容器。

导入商品#

导出 Ecwid 商品和变体 SKU 字段，并将它们映射到 ideal.house sku。使用 商品上传，包括 导入商品、任务状态、列出商品、更新商品、删除商品 和 错误与重试。

任何 Ecwid REST API 导出、webhook、OAuth 安装或周期同步均为客户所有，必须在服务端使用适当的 Ecwid 授权实现。

验证与移除#

测试应用安装、API 初始化、商品/分类/搜索过渡、每个变体、缺失和未知 SKU、浏览器 Back/Forward、嵌入到其他站点的 Ecwid 组件、移动端布局、用户同意以及登录/未登录客户。确认 SDK 请求发生在包含宿主容器的同一文档中，并确认 SKU 完全一致。

如需移除，将自托管 JavaScript 文件从自定义应用中分离，或卸载应用，移除注入的 host/监听器，并验证经过店铺前台导航和硬刷新后 SDK URL 和所有 data-idealhouse-* 节点消失。

官方平台参考#