BigCommerce集成#

通过仅加载一次SDK并将当前商品或变体SKU渲染到生成按钮容器中，将Room Visualizer添加到BigCommerce Stencil店铺前台。

**验证状态：**BigCommerce开发者文档已于2026年9月7日审阅。无测试商店可用。Stencil和Catalyst有不同的渲染和导航模型；本指南提供可操作的Stencil路径，并将Catalyst店铺前台导向框架适配器。

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

选择店铺前台路径#

• **Stencil：**通过脚本管理器或脚本API安装加载器，然后在自定义主题模板中添加容器。
• Catalyst： 在 Catalyst React/Next.js 应用中添加脚本和组件；参阅 React / Next.js。
• **旧版Blueprint：**迁移到受支持的店铺前台，或由BigCommerce开发者确定安全的插入点。当前脚本API文档将Blueprint单独处理。

您需要主题编辑权限、暂存主题/频道、ideal.house Shop ID 和 Publishable Key，以及至少一个已导入到ideal.house的BigCommerce SKU。

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

容器的商品代码必须与已导入的目录sku完全匹配。本指南不假设存在一个ideal.house BigCommerce应用。

在Stencil上安装#

在店铺前台→脚本管理器中，为相关店铺前台/频道及商品页面创建页脚脚本。从示例中仅粘贴SDK脚本标记，带上您的浏览器安全凭据。脚本管理器是面向通道的脚本API的控制面板对应物。

对于可复用的应用，改用BigCommerce的脚本API。该API操作和应用OAuth流程是您集成服务的责任；不要在店铺前台代码中暴露其访问令牌。

确认仅存在一个SDK标记。不要将其同时包含在templates/layout/base.html中。

渲染初始商品#

在自定义Stencil主题中，在您主题使用的商品视图局部文件中，将容器添加到商品表单附近：

{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

确切的局部文件因主题而异。使用Stencil CLI预览定制后的主题，并将更改保留在版本控制的主题中，而不是编辑生成的店铺前台HTML。

对于卡片，仅在卡片上下文中暴露您所导入的确切SKU时才渲染容器。带选项的商品在分类页上可能没有最终变体SKU；除非购物者已选择完整变体，否则链接到商品页面。

同步商品选项#

Stencil主题JavaScript通过主题特定的商品详情代码接收商品选项变更。在当前主题已解析最终变体响应的位置添加客户适配器：

export function replaceIdealhouseContainer(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);
}

从您的主题回调中传递已解析的变体SKU。BigCommerce主题可以自定义或替换默认的商品详情实现，因此本指南不虚构全局选项变更事件。在插入新容器之前，移除旧容器。

快速查看与动态页面#

快速查看、分层搜索、分页和客户端导航可能会替换商品DOM。在每个渲染模板中添加干净的容器，并在主题的文档化渲染回调后调用相同的桥接器。请勿克隆已被SDK填充的容器。

Catalyst使用客户端React渲染，没有Stencil Handlebars上下文。在应用shell中仅加载一次SDK，并按React/Next.js指南中以所选变体SKU为键的方式处理可视化器组件。

导入和映射商品数据#

将BigCommercesku值映射到ideal.housesku；对于变体，使用每个变体SKU而非父商品ID。BigCommerce目录数据不会通过浏览器SDK同步。

使用商品上传作为批准的导入契约，然后查阅导入商品、任务状态、列出商品、更新商品、删除商品和错误与重试。任何BigCommerce API导出、Webhook或定时同步均由客户操作适配器完成。

验证与移除#

上线前，测试简单商品、每个选项组合、不含SKU的商品，以及ideal.house中缺失的SKU。检查商品页面、分类卡片、快速查看、分层导航、浏览器后退/前进、移动端布局、同意行为以及每个活跃的店铺前台通道。在DevTools中，验证一次成功的SDK请求以及精确的商品代码/SKU匹配。

要移除集成，请删除脚本管理器条目或脚本API记录，移除所有主题容器标记和适配器代码，发布干净的主题，然后清除店铺前台/CDN缓存。确认每个通道中均无SDK请求。

官方平台参考#

• BigCommerce脚本API与脚本管理器
• BigCommerce Stencil主题文档
• BigCommerce自定义Stencil JavaScript
• BigCommerce Catalyst文档