Ideal House
跳转到主要内容

SHOPLINE 集成#

通过主题应用扩展或受控自定义主题区块，将 Room Visualizer 集成到 SHOPLINE 网上店铺。

验证状态： SHOPLINE Online Store 2.x/3.0 主题文档已于 2026年9月7日 审核。无合作方应用或商家测试店铺可用。模板语法和支持的扩展类型因 Online Store 代际而异，请针对实际店铺版本进行验证。

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

选择集成方式#

  • 对于 Online Store 2.0/2.1 的可复用公开应用，SHOPLINE 推荐使用带 App Block 和可选 App Embed Block 的 Theme App Extension。
  • Online Store 3.0 主题提供可复用区块，支持可选的 JavaScript 资源和 App Blocks。
  • Script Tag/Asset APIs 属于旧版或依赖版本/应用类型；在未核对 SHOPLINE 兼容性表前请勿选用。
  • 对于单店主题定制，使用当前版本的区块/模板和资源结构。

准备开发店铺、扩展/主题访问权限、Shop ID、Publishable Key，以及已导入的商品变体编码。

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

Product Code 必须与 ideal.house 目录的 sku 匹配。本文档不声称存在可安装的 ideal.house SHOPLINE 应用。

构建主题区块#

创建一个 App Block 或公开主题区块，在商品详情页渲染一个 host。使用你的 Online Store 代际文档中记录的精确商品/变体对象和转义辅助函数。最终的店铺前台 HTML 应为：

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

在模板源码中，将 CHAIR-OAK-01 替换为当前已选变体的 SKU/code 表达式。不要将 Shopify Liquid 表达式粘贴到 SHOPLINE 3.0 Handlebars 模板中；这是不同的语言和对象契约。

对于 App Block，在 Theme Editor 的 product section 中添加它。对于 App Embed，用它在全局加载 SDK 而无需可见 UI。App Block 通常需要在安装后由商家启用/放置。

加载 SDK 一次#

在扩展/主题的 JavaScript 资源中，创建带有两个公开设置的脚本，然后再追加：

js
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);
}

使用扩展配置/动态参数来管理多商家凭证。仅暴露 Publishable Key；应用密钥保留在你的服务端。

已选变体与动态区块#

将当前主题的已记录商品选择回调连接到客户适配器：

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

SHOPLINE 主题支持自定义，因此本指南不发明通用的店铺前台变体事件。Online Store 3.0 记录了主题编辑器区块/部分事件，但那是编辑器生命周期事件，而非购物者变体选择事件。

当区块、筛选器、分页、快速预览或主题编辑器预览重新渲染商品节点时，创建一个全新的容器。当区块在 Theme Editor 卸载时清理监听器。商品卡片的按钮需要基于条目级 SKU；当最终变体未知时省略控制。

导入商品#

导出 SHOPLINE 商品和变体数据，并将选定的店铺前台编码映射到 ideal.house sku。使用 商品上传 和经批准的 导入、任务状态、列出商品、更新商品、删除商品、重试处理 指南。

SHOPLINE Admin API 同步、webhooks、应用 OAuth 和应用商店分发是客户适配器工作。

验证与移除#

测试安装和商家区块启用、简单商品、每个变体、缺失/未知编码、卡片、快速预览、筛选器、SPA 风格导航、移动端、用户同意、主题编辑器预览，以及每个受支持的 Online Store 版本。确认一次 SDK 请求，以及精确的 code/SKU 映射。

如需移除，禁用 App Block/Embed 并卸载扩展，或移除自定义区块和资源。发布干净的 theme，清除缓存，验证没有 SDK URL 或 data-idealhouse-* 标记残留。

官方平台参考#