Webflow 集成#
使用 Webflow Custom Code 及 CMS/Ecommerce 字段渲染 Room Visualizer 按钮，其 Product Code 需匹配 ideal.house 目录。
验证状态： Webflow 帮助中心文档已于 2026年9月7日 审核。无客户 Webflow 站点可供测试。Custom code 在预览/发布后运行，且 Webflow 不在 Embed 中运行服务端代码，因此请在已发布的暂存域名上测试。
加载 SDK 之前： 打开 Dashboard → Settings，将你的店铺前台来源添加到 Allowed Origins (CORS)，然后点击 Save。包含已发布的域名以及任何预览或暂存环境来源；多个来源用逗号分隔。参见配置步骤。
前提条件与限制#
你需要使用 Custom Code 或 Code Embed 的权限、暂存域名、Shop ID、Publishable Key 和一个已导入的目录 SKU。Webflow 套餐要求适用于 JavaScript 嵌入。浏览器中可以包含 Publishable Key，但绝不应有 Client Secret 或 AI API 密钥。
SDK 不会自动读取 Webflow Ecommerce。你的模板必须暴露该 SKU，或者由客户适配器从可信 CMS 字段中推导。
最小化 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>
data-product-code 必须精确等于导入的 ideal.house sku。
安装加载器#
打开 Site settings → Custom code，将 SDK 脚本标签添加到页脚/body 末尾区域。替换占位符，保存并发布。在站点级别安装一次；不要在每个 CMS 条目中重复安装。
Webflow 的 Designer 画布可能不会执行脚本。请在预览或已发布的暂存 URL 上验证，并检查实际页面源码。
添加条目级按钮#
创建一个名为 Idealhouse SKU 的纯文本 CMS 字段。使用与导入的 ideal.house sku 相同的值填充。在 Product 或 CMS Collection 模板中，在按钮应出现的位置添加 Code Embed：
<div
data-idealhouse-button-container
data-product-code="[bind this attribute to the current item's Idealhouse SKU]"
></div>
使用 Webflow Embed 编辑器中的 Add field 控件插入当前条目的值；上方方括号中的说明不是字面生产标记。发布后，检查 DOM 并确认它变成了类似以下的普通字符串：
<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>
对于静态页面，粘贴字面量 SKU。除非该精确值是导入的 ideal.house SKU，否则不要使用页面 slug 或 Webflow 条目 ID。
变体与动态渲染#
Webflow 的标准 Designer 绑定未必能在所有 Ecommerce 布局中将最终变体 SKU 暴露给任意自定义代码。如果每个视觉选项需要不同的 ideal.house 资源，则构建客户适配器从支持的 Webflow 集成或你自己的数据层接收所选变体，然后替换容器：
function showIdealhouseVariant(host, sku) {
host.replaceChildren();
const code = typeof sku === 'string' ? sku.trim() : '';
if (!code) return;
const node = document.createElement('div');
node.dataset.idealhouseButtonContainer = '';
node.dataset.productCode = code;
host.append(node);
}
这是客户代码。从你实际使用的变体工具中记录好的回调函数调用它。不要抓取显示的选项文本或假设存在非官方的 Webflow 事件。
Webflow 交互、CMS 过滤器、第三方分页和 SPA 式转场可能会添加或替换 Collection Items。将 Embed 包含在每个条目模板内，或在该工具的记录渲染回调后调用桥接。始终创建新容器，而非克隆已处理的 SDK 标记。
导入目录数据#
导出你的 Webflow Product/CMS 字段并将 Idealhouse SKU 映射到 sku。通过 商品上传 上传，并遵循 导入商品、任务状态、列出商品、更新商品、删除商品 和 错误与重试。
浏览器 SDK 不提供自动 Webflow 同步。任何 CMS API 导出、Webhook 或自动化均由客户负责。
验证与移除#
发布到暂存环境并测试映射条目、缺失字段、未知 SKU、Collection List、产品模板、过滤器/分页、弹窗、移动端断点、同意控制和浏览器后退/前进。确认 SDK 只加载一次，每个渲染代码匹配当前条目，且服务器凭证不出现在 HTML 中。
要移除，删除站点级 SDK Custom Code 和每个 Embed/按钮绑定，重新发布，并清除任何代理/CDN 缓存。确认脚本请求和 data-idealhouse-* 元素已从已发布站点中消失。