Ideal House
Skip to content

Custom storefront developer integration#

Load the ideal.house SDK and map storefront productCode values to Catalog.

<!-- DASHBOARD_READINESS -->

Before loading the SDK: Open Dashboard → Settings, add your storefront origin to Allowed Origins (CORS), and click Save. Include the published hostname and any preview or staging origins you use; separate multiple origins with commas. See configuration steps.

1. Load the SDK#

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

2. Choose one button contract#

Option A: SDK-generated button#

Render a target container. After product validation, the SDK creates its child button.

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

Option B: authored button#

Render and style the button yourself. The SDK preserves the DOM and binds eligibility plus click behavior.

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

3. Keep productCode identical to Catalog#

<PRODUCT_CODE>

  • Catalog productCode and storefront data-product-code must be identical, including case.
  • Do not regenerate productCode from a mutable name on every render; update Catalog and storefront together when it must change.

4. Handle dynamic pages and selected products#

The SDK observes targets inserted after page load. Your application must still update target attributes and reset old SDK state when the selected product changes.

Update an authored button after selection changes#

js
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. Verify the integration#

  1. The Network panel shows sdk.js loaded with HTTP 200.
  2. The matched target data-product-code exactly matches Catalog.
  3. Only eligible products show a generated or authored button.
  4. Dynamic product changes update the target before the customer clicks.
  5. Clicking the button opens the ideal.house Viewer with the selected product.
<!-- DASHBOARD_CONFIGURATION -->

Advanced configuration#

Server-generated launch token#

Use this mode when your backend issues short-lived launch tokens. Client Secret must never appear in browser 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"}'

Custom product size#

Provide width, height, and lowercase unit (ft, in, or cm) together on the matched element. The SDK reads the latest values at click time.

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>