Shoplazza 集成#

使用 Theme App Extension 或自定义 Liquid 主题将 Room Visualizer 添加到 Shoplazza，并将已选变体的 SKU 渲染为 ideal.house Product Code。

验证状态： Shoplazza 主题、扩展、商品和变体文档已于 2026年9月7日审核。由于无合作方应用或商家测试店铺可用，安装和变体切换必须在开发店铺中验证。

加载 SDK 之前： 打开 Dashboard → Settings，将你的店铺前台来源添加至 Allowed Origins (CORS)，然后点击 Save。包含已发布的域名以及你使用的任何预览或预发来源；多个来源用逗号分隔。参见配置步骤。

前置条件#

准备一个 Shoplazza 开发/商家店铺、主题或应用扩展源码访问权限、Shop ID、Publishable Key，以及支持变体 SKU 的已导入记录。在自定义前复制商家主题。

Theme App Extension 是可持续维护的可复用路径。App Block 注入可见 UI，必须由商家添加到兼容的商品 section；App Embed 可以加载全局行为。

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

Shoplazza 记录了 variant.sku；使用该精确字符串作为 ideal.house sku。

添加 App Block#

为 product section 创建主题扩展 App Block。Shoplazza Liquid 区块在商品上下文中可访问 product。从空 host 开始，然后使用当前主题的 product-form 状态提供已选变体：

liquid

<div class="idealhouse-host"></div>

{% schema %}
{
  "name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
  "target": "section",
  "javascript": ["idealhouse.js"],
  "settings": []
}
{% endschema %}

对于单变体商品，区块的 JavaScript 可以从主题安全序列化的数据中读取 product.variants 中唯一记录的条目。对于多变体商品，保持 host 为空，直到主题的已有 product form 解析出选择。这避免依赖未记录的 selected-variant Liquid 属性。

加载 SDK#

在 idealhouse.js 中，加载 SDK 一次。对于可复用应用，通过安全的公开区块/embed 配置提供 Shop ID 和 Publishable Key，而非硬编码单一商家：

if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
  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);
}

切勿暴露应用密钥或 ideal.house Client Secret。

保持已选变体同步#

将主题的已记录 product-form 回调连接到该适配器：

function renderIdealhouseVariant(host, variant) {
  host.replaceChildren();
  const code = String(variant && variant.sku || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Shoplazza 的 variant 对象记录了 sku，但主题可以以不同方式实现选择。回调接线是客户适配器工作。在新选择后重建容器；不要仅变更 SDK 填充的标记。

对于 collection 卡片、快速预览、搜索筛选器和客户端渲染区块，添加条目级 host，并在主题已记录的渲染回调后运行 bridge。如果卡片上尚未确定最终变体，请不显示按钮，或改为提供商品详情页链接。

导入商品#

导出所有受支持的 variant.sku，并通过商品上传导入为 ideal.house sku。参见导入商品、任务状态、列出商品、更新商品、删除商品和错误与重试。

Admin API 导出、webhooks、计划同步、OAuth 和扩展分发是客户实现工作。

验证与移除#

测试 App Block 放置、Embed 启用、单变体商品、所有多变体选项、空白/重复/未知 SKU、collection 卡片、快速预览、筛选器、浏览器历史、移动端、本地化/货币、用户同意和主题预览/线上模式。确认一次 SDK 请求，以及精确的变体 SKU 映射。

如需移除，禁用并卸载 Theme App Extension，或移除自定义 Liquid/JavaScript，发布干净的 theme，清除店铺前台缓存，并验证 SDK 及所有 data-idealhouse-* 节点消失。