Squarespace 集成#
通过 Code Injection 在 Squarespace 上安装 Room Visualizer，并在页面编辑器允许自定义代码的位置放置产品特定容器。
验证状态： Squarespace 帮助中心文档已于 2026年9月7日 审核。无客户 Squarespace 站点可供测试。Code Injection 和 JavaScript Code Blocks 需要符合条件的套餐，自定义代码不在 Squarespace 支持范围内，且 Ajax 加载可能影响其运行。
加载 SDK 之前： 打开 Dashboard → Settings，将你的店铺前台来源添加到 Allowed Origins (CORS)，然后点击 Save。包含已发布的域名以及任何预览或暂存环境来源；多个来源用逗号分隔。参见配置步骤。
范围与前提条件#
此路径最适合目录较小且产品页面稳定的情况，或你掌控明确的产品代码数据层的站点。你需要符合条件的套餐、站点所有者权限、Shop ID、Publishable Key 和已导入的 ideal.house SKU。
Squarespace 在本指南中不提供 ideal.house 扩展。其标准产品编辑器不保证为选定变体 SKU 提供稳定的公开 JavaScript API，因此变体级别的匹配需要客户适配器工作，且不一定在所有模板上都实用。
最小化 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 必须精确匹配导入的目录 sku。不要在 Code Injection 中使用 Client Secret。
安装加载器#
打开 Website → Pages → Custom Code → Code Injection（标签可能因站点版本而异）。将 SDK <script> 粘贴到 Footer 中，替换两个占位符并保存。页脚注入在网站页面于 </body> 之前运行；结账页面不支持注入代码。
加载器仅安装一次。如果其他集成已添加，请移除重复项。
放置产品按钮#
在页面编辑器允许 JavaScript Code Block 的位置放置：
<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>
使用该确切产品的 SKU。在 Squarespace 7.1 中，Store/Product Details 布局可能不接受主产品信息区域的任意区块。一个实用的替代方案是使用带 Product Block 和相邻 Code Block 的正常布局页面，每种产品一对。确认商店页面保持启用状态，因为 Product Blocks 依赖它。
对于较大目录，开发人员可以通过匹配稳定的客户所有权映射（如 URL 路径到 SKU）注入容器：
const skuByPath = {
'/shop/oak-chair': 'CHAIR-OAK-01',
'/shop/walnut-chair': 'CHAIR-WALNUT-01'
};
function renderForPath() {
const host = document.querySelector('[data-idealhouse-host]');
const sku = skuByPath[location.pathname];
if (!host) return;
host.replaceChildren();
if (!sku) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = sku;
host.append(container);
}
URL 映射、host 插入和导航回调是客户代码。不要抓取私有 Squarespace 状态或假设其形状稳定。
变体、快速查看与 Ajax 加载#
如果一个 Squarespace 产品有多个具有不同 ideal.house 资源的变体，仅在适配器能从支持来源识别所选变体 SKU 后才显示按钮。每次变更时用干净的容器替换旧容器。如果不存在支持的选择回调/数据源，仅当所有变体共享相同视觉资源时才使用一个共享的产品级 SKU，否则省略按钮。
Quick View、Product Blocks 和 Ajax 页面加载可替换页面内容。Squarespace 警告 Ajax 加载可能与自定义代码冲突。测试确切模板；如有必要，禁用 Ajax 加载或从你拥有的导航机制中调用 renderForPath()。MutationObserver 是最后手段的客户适配器，应限定在产品区域范围内。
导入产品数据#
维护一张 Squarespace 产品/变体 SKU 到 ideal.house sku 的映射表，然后使用 商品上传。完整的公开工作流记录在 导入商品、任务状态、列出商品、更新商品、删除商品 和 错误与重试 下。
浏览器 SDK 不同步 Squarespace 产品。任何 Commerce API 导出、Webhook 或定时任务均由客户负责。
验证与移除#
在隐私窗口中测试已发布站点，因为已登录编辑可能会抑制自定义代码。检查一个映射产品、一个缺少 SKU、一个未知 SKU、Product Blocks、Quick View、Ajax 导航、浏览器后退/前进、移动端布局、Cookie 同意和结账排除。确认一个成功的 SDK 请求及精确的 Product Code/SKU 相等。
要移除，删除 Footer 注入及所有 Code Blocks/host/映射脚本，保存并清除缓存。验证已发布页面没有 SDK 请求或 data-idealhouse-* 元素。