自定义店铺前台开发者集成#

加载 ideal.house SDK 并将店铺前台 productCode 值映射到 Catalog。

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

1. 加载 SDK#

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

2. 选择一种按钮契约#

选项 A：SDK 生成的按钮#

渲染目标容器。完成商品验证后，SDK 会创建其子按钮。

html

<div data-idealhouse-button-container data-product-code="<PRODUCT_CODE>"></div>

选项 B：手动编写的按钮#

自行渲染和样式化按钮。SDK 保留 DOM 并绑定资格和点击行为。

html

<button
  type="button"
  data-idealhouse-authored-button
  data-product-code="<PRODUCT_CODE>"
  style="visibility: hidden;"
>
  View in my room
</button>

3. 保持 productCode 与 Catalog 一致#

<PRODUCT_CODE>

Catalog productCode 与店铺前台 data-product-code 必须完全一致，包括大小写。
不要在每次渲染时从可变的名称重新生成 productCode；必须在必须更改时同步更新 Catalog 和店铺前台。

4. 处理动态页面和已选商品#

SDK 观察页面加载后插入的目标。您的应用程序仍需在所选商品变化时更新目标属性并重置旧的 SDK 状态。

在选择变更后更新手动编写的按钮#

const button = document.querySelector('[data-idealhouse-authored-button]')

function selectProduct(product) {
  button.dataset.productCode = product.productCode
  button.dataset.active = 'false'
  button.style.visibility = 'hidden'

  delete button.dataset.rvProductCode
  delete button.dataset.rvProductType
  delete button.dataset.rvProductId
  delete button.dataset.rvProductIds
}

5. 验证集成#

Network 面板显示 sdk.js 加载成功，HTTP 状态码为 200。
匹配的目标 data-product-code 与 Catalog 完全匹配。
只有符合条件的商品才会显示生成或手动编写的按钮。
动态商品变更会在客户点击之前更新目标。
点击按钮会打开 ideal.house Viewer 并展示所选商品。

高级配置#

服务器生成的 launch token#

当您的后端签发短期 launch token 时使用此模式。Client Secret 绝不应出现在浏览器 JavaScript 中。

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-launch-token="<SERVER_GENERATED_LAUNCH_TOKEN>"
  async
></script>

bash

# Run on your server. Never expose CLIENT_SECRET in browser JavaScript.
curl -X POST "<IDEALHOUSE_API_URL>/shops/<SHOP_ID>/sdk-launch-token" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <CLIENT_ID>" \
  -H "x-client-secret: <CLIENT_SECRET>" \
  -d '{"origin":"https://your-store.example"}'

自定义商品尺寸#

在匹配的元素上一起提供 width、height 和小写单位（ft、in 或 cm）。SDK 会在点击时读取最新的值。

html

<button
  data-idealhouse-authored-button
  data-product-code="<PRODUCT_CODE>"
  data-product-width="8"
  data-product-height="10"
  data-product-size-unit="ft"
  style="visibility: hidden;"
>View in my room</button>