Wix集成#

通过与您站点类型匹配的Wix扩展接入方式，将Room Visualizer与 Wix Stores 集成。Wix Editor 与 Wix Studio 需要不同的方法。

**验证状态：**Wix扩展文档已于2026年9月7日审阅。由于无法获取客户Wix站点或应用凭据，因此未完成端到端认证。SDK必须与其容器共享店铺前台DOM；HTML iframe不能替代。

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

选择正确的Wix路径#

Wix文档说明商店嵌入式脚本在 Wix Studio 中不可用，并引导应用使用站点插件扩展。请勿安装编辑器嵌入式脚本方案并声称支持工作室。

前置条件#

准备一个带有 Wix Stores 的Wix测试站点，具备发布自定义代码或应用扩展的权限，以及ideal.house Shop ID 和 Publishable Key，并导入测试SKU。确定所选Wix变体是否有自己的SKU。将所有应用密钥和后端API密钥移出浏览器页面。

最小SDK标记#

当Wix允许代码在店铺前台文档中运行时，支持的ideal.house标记如下：

<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.housesku完全匹配。

Wix Editor：为单一站点安装#

在 Wix 控制面板中，通过 设置 → 自定义代码 添加 SDK 标签，将其放置在 body/body 末尾，并选择需要它的商品页面。发布站点；预览模式不足以进行生产环境检查。

然后添加一个商品页自定义元素或 Wix Stores 扩展点，使其在同一顶级文档中生成容器。避免对按钮使用Wix HTML嵌入：它在iframe中运行，因此父文档中的脚本无法发现其容器，而iframe中的脚本也无法控制商品页面。

可放置元素应在您的代码中暴露一个操作：

function setIdealhouseSku(host, sku) {
  host.replaceChildren();
  const code = typeof sku === 'string' ? sku.trim() : '';
  if (!code) return;

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

仅在Wix通过您页面或扩展可用的API报告了完整的当前商品/变体后，才调用它。这是客户适配器代码；它有意不命名未经核实的Wix页面事件。

Wix应用：为 Wix Editor 商店的嵌入式脚本#

Wix Stores 为嵌入式脚本扩展提供details-placeholder和bottom-placeholder位置。向其中一个占位符追加宿主容器；不要替换其内容，因为其他应用可以共享它。将SDK脚本配置为独立的嵌入片段，或使用精确的src、data-shop-id和data-publishable-key属性以编程方式创建它。

CLI创建的嵌入式脚本可用的Wix站点API可以读取店铺前台上下文。通过Wix支持的商店API解析当前变体SKU，然后调用您的setIdealhouseSku()桥接器。在存在完整SKU之前，保持占位符为空。

Wix Studio：站点插件#

创建一个针对文档化商品页槽位的 Wix Stores 站点插件。从插件UI渲染容器，并在Wix渲染的站点文档中加载SDK。插件必须将其解析的当前变体SKU传递给DOM容器。Wix Studio 的槽位名称和组件API可能演进；在生成扩展时从当前CLI/API参考中选取，而非从此指南中复制名称。

请勿使用在隔离iframe内渲染控件的插件槽位：SDK及其查看器未针对该边界认证。选择一个将容器放置在店铺前台文档中的Wix扩展点，或使用您能控制文档的无头店铺前台。

商品映射与导航#

将Wix商品或变体sku映射到ideal.housesku。不要静默回退到Wix商品ID，因为生成的ID不会与目录SKU匹配，除非您有意导入了它。

Wix商品页面可在选项选择或客户端导航期间替换内容。在每个记录的商品/选择回调上：

1. 清除之前渲染的容器；
2. 解析完整的已选变体；
3. 插入带有其SKU的新容器；
4. 当不存在完整或可可视化的SKU时，将宿主容器留空。

对于画廊和 repeater，每个项目都需要自己的项目级SKU。快速查看和模态商品在模态槽位中需要相同生命周期桥接。

导入商品#

Wix Stores 不会与ideal.house自动同步。导出Wix商品和变体字段，将每个期望的Wix SKU设置为sku，并使用商品上传。参见导入商品、任务状态、列出商品、更新商品、删除商品以及错误与重试。

自动化的Wix到ideal.house同步、应用安装流程或Wix Webhook处理器属于客户方工作；本指南不提供此类保证。

发布前验证#

1. 在桌面和移动设备上，于无痕浏览器窗口中测试已发布的站点。
2. 确认SDK在与容器相同的文档中仅加载一次。
3. 将DOM商品代码与已导入的SKU精确对比。
4. 更改每个选项直至选定最终变体；确认旧容器已移除且新容器出现。
5. 测试Wix客户端导航、商品画廊/repeater页面、快速查看、浏览器后退/前进、同意设置、会员/已登出模式。
6. 确认未知或空的SKU不会留下损坏的可视化控件。
7. 对于应用，在单独的 Wix Editor 和工作室测试站点中测试安装、启用、禁用和卸载（按支持情况）。

移除集成#

删除或禁用Wix自定义代码条目并移除商品页元素。对于应用，移除嵌入式脚本或站点插件扩展，并从测试站点卸载它。发布后，确认脚本请求及所有data-idealhouse-*节点均已消失。

官方平台参考#

• Wix：使用嵌入式脚本自定义 Wix Stores
• Wix：关于嵌入式脚本
• Wix：关于站点扩展
• Wix：自定义元素