Ideal House
跳转到主要内容

WooCommerce 集成#

在 WooCommerce 商品页面中添加 Room Visualizer 按钮，并保持 ideal.house 商品代码与所选变体的 SKU 同步。

验证状态： 文档及公开的 WooCommerce 行为已于 2026年9月7日 审核。本实现尚未在客户商店中认证。经典模板、区块主题、变体扩展和快速查看插件可能渲染出不同的 DOM；请在暂存环境上测试完整的堆栈。

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

范围和前置条件#

本指南面向 WordPress 上的 WooCommerce。它使用一个小型站点特定插件或子主题、标准的 WordPress 资源加载器以及 WooCommerce 商品钩子。它不是一个可安装的 ideal.house WordPress 插件。

准备管理员和文件访问权限、Shop ID、Publishable Key，以及每个可可视化 SKU 的已导入 ideal.house 记录。为每个简单商品和每个受支持的变体在 WooCommerce 中提供一个非空的、唯一的 SKU。

最小 SDK 标记#

这是集成所使用的公开 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>

生成的容器代码必须与已导入的目录 sku 匹配。切勿将 WooCommerce 数据库 ID 放入 data-product-code 中，除非您特意将这些 ID 用作目录 SKU。

一次性加载 SDK#

将以下代码添加到子主题 functions.php 或站点特定插件中。替换占位符。

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    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 之前支持 WooCommerce 版本，请将 true 作为最后一个入队参数传入，并在过滤器中加 async。

渲染商品页宿主容器#

以下钩子将宿主容器放置在加入购物车表单之后。简单商品会立即获得其 SKU。可变商品开始时空白；当选择完整的变体时，浏览器适配器会填充它们。

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

确认该钩子存在于您的商品模板中。替换了 WooCommerce 模板或商品集合区块的主题可能需要区块集成或其他文档化的 WooCommerce 钩子。

同步已选变体#

WooCommerce 的捆绑变体表单会触发 jQuery 变体生命周期事件。添加一个本地文件，例如 assets/js/idealhouse-woocommerce.js，使用 jquery 和 wc-add-to-cart-variation 依赖入队，然后使用：

js
(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

此文件是客户拥有的 WooCommerce 适配器。如果变体插件替换了标准表单脚本，请使用该插件文档化的选择回调，而不要假设这些事件仍在触发。不要仅更新已被 SDK 处理过的容器的属性；请用干净的新容器替换它。

商品网格、快速查看和 AJAX 导航#

对于目录卡片，使用类似 woocommerce_after_shop_loop_item 的商品循环钩子，并渲染简单商品的 SKU。网格上的可变商品通常没有已解析的变体；请链接到商品页面或构建显式的变体选择适配器。

快速查看插件和 WooCommerce 区块可以在初始页面加载之后注入商品。将宿主容器放在它们渲染的模板中，并从该工具的文档化完成回调中运行您的 render() 桥接逻辑。如果没有稳定的回调，一个作用域受限的 MutationObserver 可能会检测到新的 .idealhouse-host 节点，但其性能和生命周期由客户负责。

目录映射与导入#

将 WC_Product::get_sku() 及每个 WC_Product_Variation::get_sku() 映射到 ideal.house sku。如果父产品和子产品代表不同的可视化资产，则不应共享同一代码。

WooCommerce 不会自动将目录更改推送给 ideal.house。请使用商品上传及其导入、任务状态、列出商品、更新商品、删除商品和重试处理指南。任何定时导出或 webhook 桥接均属于客户实现。

发布前验证#

  1. 测试一个简单商品、一个可变商品、一个缺失的 SKU 和一个在 ideal.house 中不存在的 SKU。
  2. 确认 SDK 仅被请求一次，且其脚本标签保留了两个凭证属性。
  3. 选择每一个变体并确认 data-product-code 等于变体的 SKU。
  4. 重置变体表单；旧容器应消失。
  5. 测试商品网格、快速查看、AJAX 过滤器、购物车片段、移动端吸顶加入购物车以及浏览器前进/后退（如适用）。
  6. 在注销状态下，启用同意控制和生产缓存时进行测试。
  7. 确认 Client Secret 不出现在 HTML、JavaScript、日志或源映射中。

移除集成#

移除 PHP 钩子/过滤器和本地变体适配器入队。从覆盖的模板或区块中删除宿主容器，清除 WooCommerce 瞬态和页面/CDN 缓存，然后确认不再有 SDK 请求或 data-idealhouse-* 元素残留。

官方平台参考#