BigCommerce 連携#

BigCommerce の Stencil オンラインストアに Room Visualizer を追加するには、SDK を一度だけ読み込み、現在の商品またはバリエーションの SKU を自動生成ボタンのコンテナに描画します。

検証状況: 2026年9月7日 に BigCommerce の開発者向けドキュメントを確認しました。テストストアは利用できませんでした。Stencil と Catalyst では描画と画面遷移のモデルが異なります。このガイドでは Stencil 向けの具体的な手順を示し、Catalyst のオンラインストアについてはフレームワーク用アダプターを案内します。

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

オンラインストアの方式の選択#

• Stencil: スクリプトマネージャーまたは Scripts API でローダーを設置し、独自テーマのテンプレートにコンテナを追加します。
• Catalyst: Catalyst の React/Next.js アプリにスクリプトとコンポーネントを追加します。React / Next.js に従ってください。
• 旧 Blueprint: 対応するオンラインストアに移行するか、BigCommerce の開発者に安全な挿入箇所を特定してもらってください。現在の Scripts API ドキュメントでは、Blueprint は別扱いです。

テーマの編集権限、ステージング用テーマまたはチャネル、ideal.house の Shop ID と Publishable Key、および ideal.house にインポート済みの BigCommerce の SKU が少なくとも一つ必要です。

SDK の最小構成#

<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>

コンテナの商品コードは、インポート済みカタログの sku と完全に一致する必要があります。このガイドは ideal.house の BigCommerce アプリの存在を前提としていません。

Stencil への設置#

オンラインストア → スクリプトマネージャー で、対象のストアまたはチャネルの商品ページ用にフッタースクリプトを作成します。例の SDK スクリプトタグだけを貼り付け、ブラウザーで公開可能な認証情報を指定します。スクリプトマネージャーは、チャネルに対応した Scripts API の管理画面側の機能です。

再利用可能なアプリでは、代わりに BigCommerce の Scripts API を使用します。その API 操作とアプリの OAuth フローは、連携サービス側で実装します。アクセストークンをオンラインストアのコードに公開しないでください。

SDK タグが一つだけあることを確認します。templates/layout/base.html にも重複して追加しないでください。

初期商品の描画#

独自の Stencil テーマで、使用中のテーマの商品表示用パーシャルにある商品フォームの近くにコンテナを追加します。

{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

正確なパーシャルはテーマによって異なります。Stencil CLI でカスタマイズしたテーマをプレビューし、生成済みのオンラインストアの HTML を編集せず、バージョン管理されたテーマに変更を保持します。

カードでは、そのコンテキストからインポート時と同じ正確な SKU を取得できる場合だけコンテナを描画します。選択肢のある商品では、カテゴリーページ上で最終的なバリエーションの SKU が未確定の場合があります。購入者が完全なバリエーションを選択していない場合は、商品ページへのリンクを設置します。

商品の選択肢の同期#

Stencil テーマの JavaScript は、テーマ固有の商品詳細コードを通じて選択肢の変更を受け取ります。現在のテーマが最終的なバリエーションのレスポンスを確定した箇所に、利用側のアダプターを追加します。

export function replaceIdealhouseContainer(host, sku) {
  host.replaceChildren();
  const code = typeof sku === 'string' ? sku.trim() : '';
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

テーマのコールバックから確定したバリエーションの SKU を渡します。BigCommerce のテーマは既定の商品詳細実装をカスタマイズまたは置き換えられるため、このガイドでは共通の選択肢変更イベントを仮定しません。新しいコンテナを挿入する前に、古いコンテナを削除してください。

クイックビューと動的ページ#

クイックビュー、絞り込み検索、ページ分割、クライアント側の画面遷移によって商品の DOM が置き換わる場合があります。描画する各テンプレートに新しいコンテナを追加し、テーマの公開された描画コールバック後に同じ橋渡し処理を呼び出します。SDK が内容を追加済みのコンテナを複製しないでください。

Catalyst はクライアント側の React 描画を使用し、Stencil の Handlebars コンテキストはありません。React/Next.js ガイドに示すように、アプリの外枠で SDK を一度だけ読み込み、選択中のバリエーションの SKU を可視化コンポーネントのキーにします。

商品データのインポートと対応付け#

BigCommerce の sku の値を ideal.house の sku に対応付けます。バリエーションでは親商品の ID ではなく、各バリエーションの SKU を使用します。ブラウザー用 SDK は BigCommerce のカタログデータを同期しません。

承認されたインポート仕様は商品アップロードを参照し、商品インポート、ジョブの状態、商品一覧、商品更新、商品削除、エラーと再試行も確認します。BigCommerce の API エクスポート、Webhook、定期同期は、利用側が運用するアダプターです。

検証と削除#

公開前に、シンプル商品、すべての選択肢の組み合わせ、SKU がない商品、ideal.house に存在しない SKU をテストします。商品ページ、カテゴリーのカード、クイックビュー、絞り込みによる画面遷移、ブラウザーの戻る・進む、モバイル表示、同意の動作、有効な各ストアチャネルを確認します。開発者ツールで SDK のリクエストが一回だけ成功し、商品コードと SKU が完全に一致することを検証します。

連携を削除するには、スクリプトマネージャーの項目または Scripts API のレコードを削除し、テーマのコンテナマークアップとアダプターコードをすべて削除します。削除後のテーマを公開し、オンラインストア/CDN のキャッシュを消去します。すべてのチャネルで SDK のリクエストがないことを確認してください。

プラットフォームの公式リファレンス#

• BigCommerce の Scripts API とスクリプトマネージャー
• BigCommerce Stencil テーマのドキュメント
• BigCommerce Stencil の JavaScript のカスタマイズ
• BigCommerce Catalyst のドキュメント