Ecwid 連携#

Ecwid の独自ストアアプリと、公開されている Storefront JS API のライフサイクルを使用して、Ecwid の商品ページに Room Visualizer コントロールを追加します。

検証状況: 2026年9月7日 に Ecwid の Storefront JS API ドキュメントを確認しました。Ecwid アプリやマーチャントのテストストアは利用できませんでした。デプロイ前に、現在の OnPageLoaded リファレンスでページのペイロードの正確なフィールドを確認する必要があります。

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

前提条件と対応する方式#

Ecwid で継続的に維持できるストアのカスタマイズを行うには、自身でホストする JavaScript ファイルを持つ独自アプリが必要です。Ecwid の開発用ストアとアプリ、HTTPS でホストしたアダプターファイル、Shop ID、Publishable Key、インポート済みの商品またはバリエーションの SKUs を用意します。

Ecwid を別の CMS に埋め込んでいる場合も、独自ストアアプリは Ecwid のストアと一緒に実行されるため、コードを配置する確実な場所です。埋め込み方式によっては、親ページのスクリプトが同じライフサイクルやドキュメントを共有しない場合があります。

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>

ideal.house の sku としてインポートした、正確な Ecwid の SKU を使用します。

Ecwid ストアアプリの初期化#

Ecwid の独自ストア向けクイックスタートに従い、自身でホストするファイルを登録します。公開されている API の準備完了コールバックから開始し、ideal.house の SDK を一度だけ読み込みます。

Ecwid.OnAPILoaded.add(function () {
  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);
});

複数ストア向けアプリでは、アプリの安全な公開設定から二つの公開 ideal.house 値を取得します。このファイルに Ecwid のアプリシークレット、アクセストークン、ideal.house の Client Secret を含めないでください。

商品ページでの描画#

Ecwid は Ecwid.OnPageLoaded.add() を公開し、そのコールバックにページ情報を渡します。現在の API リファレンスで商品ページの種類と識別子を確認し、Ecwid の対応するクライアントインターフェースから商品データを取得または読み取って、確定した SKU を以下に渡します。

function mountIdealhouse(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);
}

Ecwid がページを描画し終えた後、商品詳細内の安定した場所に host を挿入します。ページの種類が変わったら以前のホスト要素を削除します。Ecwid のストアレイアウトやペイロードのバージョンは変わる可能性があるため、DOM セレクターとページペイロードからの商品検索は、利用側のアダプターで実装します。

選択肢と画面遷移#

購入者が商品の選択肢を選ぶと、Ecwid が購入可能なバリエーションとその SKU を確定するまで待ちます。その SKU で mountIdealhouse() を呼び出し、選択が未完了の場合はホスト要素を空にします。選択肢のラベルを連結してコードを作らないでください。

Ecwid はシングルページのオンラインストアです。ブラウザーの DOMContentLoaded だけを監視せず、公開されたページのライフサイクル（OnPageLoaded やページ切り替えコールバック）を使用します。カテゴリーと検索の画面遷移、ブラウザーの戻る・進む、埋め込みウィジェット、商品ポップアップでは、古い商品のホスト要素を削除し、描画後に新しいコンテナをマウントする必要があります。

商品のインポート#

Ecwid の商品とバリエーションの SKU フィールドをエクスポートし、ideal.house の sku に対応付けます。商品アップロードと、商品インポート、ジョブの状態、商品一覧、商品更新、商品削除、エラーと再試行を使用します。

Ecwid の REST API エクスポート、Webhook、OAuth によるインストール、定期同期は利用側で管理し、適切な Ecwid の認可を使ってサーバー側に実装する必要があります。

検証と削除#

アプリのインストール、API の初期化、商品・カテゴリー・検索間の遷移、すべてのバリエーション、欠落または不明な SKUs、ブラウザーの戻る・進む、別サイトに埋め込んだ Ecwid ウィジェット、モバイル表示、同意管理、ログイン中とログアウト中の顧客をテストします。ホスト要素を含むドキュメント内で SDK のリクエストが一回だけ行われ、SKU が完全に一致することを確認します。

削除するには、自身でホストする JavaScript ファイルを独自アプリから外すか、アプリをアンインストールし、挿入したホスト要素とリスナーを削除します。ストア内の画面遷移と完全な再読み込みの後、SDK の URL とすべての data-idealhouse-* ノードがなくなることを確認します。

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

• Ecwid: JS API によるストアのカスタマイズ
• Ecwid: JS API の呼び出し
• Ecwid のストアのカスタマイズ方法