OpenCart 連携#

OpenCart 4 の拡張機能または独自テーマを通じて Room Visualizer を追加し、安定したオンラインストアの商品コードを ideal.house カタログに対応付けます。

検証状況: 2026年9月7日 に OpenCart 4 の拡張機能のドキュメントを確認しました。テストストアは利用できませんでした。OpenCart 3 と外部テーマでは、パスとイベントの規則が異なります。インストール済みのメジャーバージョンに合わせてこのガイドを調整してください。

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

前提条件とコードの選択#

ステージング用ストア、拡張機能またはテーマの開発権限、Shop ID、Publishable Key、インポート済みテストレコードを用意します。OpenCart のコアは一般に商品テンプレートで model を公開しますが、SKU についてはバージョンやテーマに応じてコントローラーまたは拡張機能の実装が必要な場合があります。一つの値を選び、ideal.house の sku として一貫して使用してください。

カタログのコアファイルを直接編集しないでください。変更を OpenCart 4 の拡張機能としてまとめるか、バージョン管理された独自テーマ内に保持します。

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 と一文字ずつ完全に一致する必要があります。

商品のコンテナの描画#

拡張機能を通じて使用中の商品テンプレートを拡張します。OpenCart の model フィールドを ideal.house の sku に意図的に対応付ける場合は、商品操作の近くに以下を配置します。

{% if model %}
  <div class="idealhouse-host">
    <div
      data-idealhouse-button-container
      data-product-code="{{ model }}">
    </div>
  </div>
{% endif %}

Twig の自動エスケープは環境設定に依存します。選択した値が HTML 属性用にエスケープされていることを確認してください。実際の SKU フィールドを選ぶ場合は、拡張機能でそのサニタイズ済みの値をコントローラーのテンプレートデータに追加し、model の代わりに描画します。

SDK を一度だけ読み込む#

拡張機能またはテーマの仕組みを通じて、オンラインストアの JavaScript アセットを追加します。必須属性を持つスクリプトを一つ作成するようにします。

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

二つの公開値を拡張機能の設定に保存し、安全に描画します。JavaScript、Twig、拡張機能のログ、キャッシュされた HTML に ideal.house の Client Secret を含めないでください。

選択肢、バリエーション、動的な描画#

OpenCart の選択肢は、必ずしも SKU を持つバリエーションと一対一に対応するわけではありません。選択肢またはバリエーションの拡張機能を使う場合は、その拡張機能で公開されているバリエーション確定コールバックとデータモデルに連携します。選択した正確なコードが得られた場合だけホスト要素を置き換えます。

function renderIdealhouseCode(host, productCode) {
  host.replaceChildren();
  const code = String(productCode || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

これは利用側のアダプターのコードです。このガイドでは共通の OpenCart バリエーションイベントを定義していません。AJAX 検索、カテゴリーフィルター、ポップアップ、クイックビューでは、拡張機能のテンプレートで新しいコンテナを描画するか、公開された完了コールバックから橋渡し処理を呼び出します。SDK が生成した子要素をコピーしないでください。

商品のインポート#

可視化する各商品について、選択した OpenCart の model または SKU をエクスポートし、ideal.house の sku に対応付けます。商品アップロードを使用し、商品インポート、ジョブの状態、商品一覧、商品更新、商品削除、エラーと再試行に従ってください。

OpenCart の管理用 API 呼び出し、定期エクスポート、イベントリスナー、Webhook は利用側で管理する連携処理です。

検証と削除#

シンプル商品、対応するすべての選択肢の組み合わせ、欠落または重複したコード、ideal.house の不明な SKUs、カテゴリーと検索ページ、クイックビュー、ブラウザーの戻る・進む、モバイル表示、複数ストア、言語と通貨、同意管理、本番のキャッシュと圧縮をテストします。SDK のリクエストが一回だけで、コードが完全に一致することを確認します。

削除するには、拡張機能を無効化またはアンインストールするか、独自テーマの上書きとアセットを削除します。OpenCart の変更とイベントを更新し、テーマ/CDN のキャッシュを消去して、SDK のリクエストとコンテナがないことを確認します。

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

• OpenCart 4: 拡張機能
• OpenCart 4: イベント
• OpenCart のドキュメント