WordPress 集成#

通过加载一个公共浏览器脚本并渲染一个容器，将 ideal.house Room Visualizer 添加到 WordPress 站点，其容器中的商品代码须与已导入目录中的 SKU 匹配。

验证状态： 本文档已于 2026年9月7日 审核。本指南尚未针对客户的 WordPress 主题进行端到端认证。在发布之前，请在您主题的精确副本及页面构建器版本上进行测试验证。

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

范围和前置条件#

本指南涵盖 WordPress 内容站点、经典主题、区块主题以及允许添加 HTML 的页面构建器。如果站点使用 WooCommerce 商品数据，请使用 WooCommerce 指南 进行变体选择。

准备工作：

• 管理员访问权限，对于持久化方法还需要子主题或小型站点特定插件；
• 来自 ideal.house 仪表板的 Shop ID 和 Publishable Key；
• 一个已导入到 ideal.house 且拥有已知 sku 的商品；
• 一个可以在测试期间禁用缓存/压缩的暂存页面。

Publishable Key 仅供浏览器标记使用。切勿将 Client Secret 或 AI API 密钥放入 WordPress HTML 中。

确认 SDK 合约#

最小支持的安装仅包含一个 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 必须等于目录 sku，包括大小写和标点符号。容器内容由 SDK 拥有。本指南中 WordPress 不提供 ideal.house 插件。

全站安装脚本#

WordPress 建议通过 wp_enqueue_script() 加载前端脚本。将以下内容添加到子主题 functions.php 或站点特定插件中。过滤器会将两个必需的数据属性添加到 WordPress 生成的标签。

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') {
        return $tag;
    }

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

替换两个占位符。WordPress 在 6.3 之前的版本不接受最终 wp_enqueue_script() 参数的数组形式；请改为传递 true，并使用 script_loader_tag 过滤器来添加 async。

不要在代码块或标签管理器中再次安装 SDK。在 DevTools 中，document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length 应返回 1。

放置按钮#

在区块编辑器中，在需要按钮的位置添加一个自定义 HTML 区块：

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

对于重复的卡片，从主题模板中渲染相同的标记，并将代码转义为 HTML 属性：

<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

您的主题或插件必须提供 $idealhouse_product_code。请勿使用文章 ID、别名或标题，除非该值也恰好是已导入的 ideal.house sku。

商品与变体映射#

在发布前创建显式的映射表：

如果页面在变体之间发生变化，客户适配器必须设置新的 data-product-code。在插入新容器之前先清除旧容器，以防止复用过期的查看器状态：

function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

这是客户适配器代码。它不会调用未记录的 ideal.house 方法或凭空捏造一个 WordPress 事件；应从您的主题或页面构建器提供的文档化回调中调用它。

动态导航和缓存#

对于 AJAX 过滤器、无限滚动、模态商品卡片或页面构建器过渡，在新商品节点进入 DOM 之后插入一个全新容器。不要克隆已被 SDK 填充过的容器。如果您的工具未暴露稳定的渲染回调，请将容器添加到其项目模板中，使每次渲染都生成干净的标记。

主题编辑后，请清除 WordPress、CDN 和优化插件的缓存。如果性能插件移除了某个数据属性或将其推迟到交互之后再执行，请将 https://sdk.ideal.house/sdk.js 排除在延迟/推迟重写之外。

导入目录数据#

WordPress 内容不会自动同步。将所选的自定义字段导出为 sku，并通过商品上传导入匹配的记录。后续可参考导入商品、任务状态、列出商品、更新商品、删除商品以及错误与重试。

发布前验证#

1. 在无痕浏览器窗口中打开暂存环境，而非 WordPress 编辑器预览。
2. 确认 SDK 请求成功返回且仅请求一次。
3. 检查容器，逐字符比较 data-product-code 与已导入的 sku。
4. 确认一个已导入的 SKU 能产生可用的查看器控件，而一个未知的 SKU 不会暴露出损坏的控件。
5. 测试页面构建器导航、过滤器、浏览器前进/后退、移动端布局和同意设置。
6. 选择每一个支持的变体，并确认容器已使用其 SKU 重新创建。
7. 检查浏览器控制台，并在启用缓存/压缩的情况下再次测试。

移除集成#

移除入队函数和 script_loader_tag 过滤器，然后删除所有 data-idealhouse-button-container 区块或模板片段。清除所有缓存，并确认页面源代码和 Network 面板中不再有 SDK URL。

官方平台参考#

• WordPress 主题手册：包含资源
• WordPress wp_enqueue_script() 参考
• WordPress 子主题