React / Next.js 集成#

在 React 或 Next.js 中直接使用 ideal.house 浏览器 SDK。本指南中没有单独的 ideal.house React npm 软件包。

验证状态： SDK 标记已对照当前 Dashboard 模板进行检查；查阅了 2026年9月7日上 React 和 Next.js 的官方生命周期/脚本文档。由于没有客户应用程序或生产凭据，端到端验证构建后的应用程序。

加载 SDK 之前： 打开 Dashboard → 设置，将您的店铺前台来源添加到 Allowed Origins (CORS) 中，然后点击 Save。包含发布的hostname以及任何预览或预发环境来源；多个来源用逗号分隔。参见配置步骤。

前提条件和边界#

准备 Shop ID、Publishable Key、已导入目录的 SKU，以及客户端渲染的商品/变体值。Publishable Key 可能出现在浏览器标记中。将 Client Secrets、AI API 密钥和任何私有商品导入凭据保留在服务器上。

SDK 会查找 DOM 容器。React 决定何时挂载这些节点；您的集成负责解析当前变体，并在 SKU 变化时替换容器。

最小的 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>

data-product-code 必须与 ideal.house 目录 sku 完全一致。

React 组件#

每当产品代码变化时挂载一个新的容器。一个 key 会强制 React 替换 DOM 节点，而不是复用可能已被 SDK 填充过的容器：

tsx

type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

传入已选择的变体 SKU，而非商品标题、路由 slug、数据库 ID 或选项标签。如果选择未完成，渲染 null。

Next.js App Router 加载器#

在覆盖商品页的最小共享布局中放置一次 SDK。Next.js 记录了对在部分水合之后加载的脚本使用 afterInteractive：

tsx

import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

从布局中渲染一次 IdealhouseSdk，然后在拥有变体选择的 Client Component 内部渲染 RoomVisualizerButton。以 NEXT_PUBLIC_ 为前缀的值会传递到浏览器；仅将它们用于 Shop ID 和 Publishable Key。

对于 Pages Router 或纯 React，在 HTML shell 中创建一次脚本，或使用单个顶层 effect：

tsx

useEffect(() => {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;
  const script = document.createElement('script');
  script.src = 'https://sdk.ideal.house/sdk.js';
  script.async = true;
  script.dataset.shopId = '<SHOP_ID>';
  script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
  document.head.append(script);
}, []);

React Strict Mode 有意执行额外的开发设置循环，因此需要重复检查。当个别商品组件卸载时，不要删除共享的 SDK 标记。

导航、列表和变体#

客户端路由更改不会重新加载布局脚本。通过稳定的路由标识以及 SKU 来 key 每个商品控件，前提是在同时挂载的多个视图中可能出现相同的 SKU。对于网格，每张卡片都需要自己的 SKU。当无限滚动添加卡片时，React 会自然挂载新的干净容器。

对于变体选择，从您的商业状态中派生 selectedVariant.sku 并作为 productCode 传入。不要调用未文档化的 SDK 刷新方法。快速查看抽屉和路由转换应卸载其之前的组件，以免已处理的 DOM 泄漏到下一个商品中。

如果 React 水合报告不匹配，请确保服务器和首次客户端渲染达成一致。在客户端商业状态解析完 SKU 之前，渲染无容器是有效的。

导入商品数据#

将商业后端的规范变体 SKU 映射到 ideal.house 的 sku。使用商品上传，然后参考导入商品、任务状态、列出商品、更新商品、删除商品以及错误与重试。

任何后端目录查询、webhook、计划同步或 launch-token 服务都属于应用程序代码；浏览器 SDK 不提供它。

验证与移除#

测试服务端渲染/水合、硬加载、客户端导航、浏览器前进/后退、变体切换、null/未知 SKU、重复卡片、快速查看、Suspense/加载状态、移动端、同意控件以及生产构建。确认只有一个 SDK 请求以及准确的 DOM Product Code/SKU 相等性。检查构建后的客户端 bundle 中是否有意外的秘密泄露。

要移除，删除共享的 SDK 组件/标记以及所有 RoomVisualizerButton 用法，移除两个公共环境变量，再次构建，并验证没有 SDK URL 或 data-idealhouse-* 标记残留。