React / Next.js 連携#

React または Next.js で ideal.house のブラウザー用 SDK を直接使用します。このガイドでは、ideal.house 専用の React npm パッケージは使用しません。

検証状況: SDK のマークアップは現在のダッシュボードのテンプレートと照合済みです。2026年9月7日に React と Next.js の公式ライフサイクルおよびスクリプトのドキュメントを確認しました。顧客のアプリケーションや本番用の認証情報は利用できなかったため、ビルドしたアプリケーションを最初から最後まで検証してください。

SDK を読み込む前に: ダッシュボード → 設定を開き、オンラインストアのオリジンを Allowed Origins (CORS) に追加して保存をクリックします。公開サイトのホスト名と、利用するプレビューまたはステージングのオリジンを含めます。複数のオリジンはカンマで区切ってください。設定手順を参照してください。

前提条件と対応範囲#

Shop ID、Publishable Key、インポート済みカタログの SKU、クライアント側で描画される商品またはバリエーションの値を用意します。Publishable Key はブラウザーのマークアップに含められます。Client Secrets、AI API キー、非公開の商品インポート用認証情報はサーバー側で保管してください。

SDK は DOM コンテナを検出します。ノードをマウントするタイミングは React が管理します。現在のバリエーションを特定し、その SKU が変わったときにコンテナを置き換える処理は、連携側で実装します。

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>

data-product-code は ideal.house カタログの sku と完全に一致する必要があります。

React コンポーネント#

商品コードが変わるたびに新しいコンテナをマウントします。key を指定すると、React は SDK がすでに内容を追加した可能性のあるコンテナを再利用せず、DOM ノードを置き換えます。

tsx

type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

選択中のバリエーションの SKU を渡してください。商品名、ルートのスラッグ、データベース ID、選択肢のラベルは使用しません。選択が未完了の場合は null を描画します。

Next.js App Router のローダー#

商品ページを含む最も限定的な共通レイアウトに、SDK を一度だけ配置します。Next.js では、ハイドレーションが一部進んだ後に読み込むスクリプト用として afterInteractive が定義されています。

tsx

import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

レイアウトから IdealhouseSdk を一度だけ描画し、バリエーション選択を管理するクライアントコンポーネント内に RoomVisualizerButton を描画します。NEXT_PUBLIC_ で始まる値はブラウザーに送信されます。Shop ID と Publishable Key にのみ使用してください。

Pages Router または通常の React では、HTML の外枠にスクリプトを一度だけ作成するか、最上位で一つのエフェクトを使用します。

tsx

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

React の Strict Mode は開発時に追加のセットアップサイクルを意図的に実行するため、重複チェックが必要です。個々の商品コンポーネントがアンマウントされても、共有の SDK タグを削除しないでください。

画面遷移、一覧、バリエーション#

クライアント側のルート変更では、レイアウトのスクリプトは再読み込みされません。同じ SKU が同時にマウントされた複数のビューに現れる場合は、安定したルート識別子と SKU を組み合わせて各商品コントロールのキーにします。グリッドでは、各カードにそれぞれの SKU が必要です。無限スクロールでカードが追加されると、React は新しい未加工のコンテナを通常どおりマウントします。

バリエーション選択では、EC サイトの状態から selectedVariant.sku を取得し、productCode として渡します。ドキュメントにない SDK の更新メソッドは呼び出さないでください。クイックビューのドロワーやルート遷移では、処理済みの DOM が次の商品に残らないよう、以前のコンポーネントをアンマウントします。

React のハイドレーションで不一致が報告される場合は、サーバーとクライアントの最初の描画結果が一致していることを確認します。クライアント側の商品状態で SKU が確定するまでコンテナを描画しない方法も有効です。

商品データのインポート#

EC バックエンドの正規のバリエーション SKU を、ideal.house の sku に対応付けます。商品アップロードを使用し、商品インポート、ジョブの状態、商品一覧、商品更新、商品削除、エラーと再試行を参照してください。

バックエンドのカタログ照会、Webhook、定期同期、起動トークンサービスはアプリケーション側で実装します。ブラウザー用 SDK はこれらを提供しません。

検証と削除#

サーバー描画とハイドレーション、ページの直接読み込み、クライアント側の画面遷移、ブラウザーの戻る・進む、バリエーション変更、空または不明な SKUs、同じ商品の複数カード、クイックビュー、Suspense と読み込み中の状態、モバイル、同意管理、本番ビルドをテストします。SDK のリクエストが一回だけで、DOM の商品コードと SKU が完全に一致することを確認します。ビルド済みのクライアントバンドルにシークレットが混入していないか調べてください。

削除するには、共有の SDK コンポーネントまたはタグと、すべての RoomVisualizerButton の使用箇所を削除し、二つの公開環境変数を削除して再ビルドします。SDK の URL や data-idealhouse-* のマークアップが残っていないことを確認してください。