Adobe Commerce / Magento Open Source 連携#

Magento のモジュールまたは独自テーマを通じて Room Visualizer を設置し、表示中のシンプル商品の SKU を ideal.house カタログに対応付けます。

検証状況: 2026年9月7日に Adobe Commerce のフロントエンドのドキュメントを確認しました。マーチャントの実環境は利用できませんでした。Luma/Blank テーマ、Hyvä、PWA Studio では JavaScript の構成が異なります。以下の具体例は、標準の RequireJS を使うオンラインストアを対象としています。

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

前提条件と対応範囲#

開発環境、独自モジュールまたは子テーマ、デプロイ権限、Shop ID、Publishable Key、インポート済みのテスト用 SKUs を用意します。vendor/ 配下やベーステーマのファイルは変更しないでください。Hyvä と PWA Studio には、それぞれ Alpine または React 向けのアダプターが必要です。RequireJS のコードをそのままコピーしてはいけません。

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>

商品コードは、インポートした正確な sku です。Magento の数値のエンティティ ID ではありません。

商品ページへのブロックの追加#

catalog_product_view 用の小さなモジュールまたはテーマのレイアウト更新を作成します。商品操作の近くに配置した .phtml テンプレートをブロックから参照します。テンプレートでは、初期の商品の SKU を安全に描画できます。

php

<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

コンフィギュラブル商品の場合、ページの初期 SKU は通常、親商品の SKU です。ideal.house のアセットが子のシンプル商品に属する場合は、ホスト要素を最初は空にし、選択したシンプル商品が確定した後でのみ内容を設定します。

SDK を一度だけ読み込む#

モジュールまたはテーマにローカルの RequireJS 初期化処理を追加します。この処理は外部スクリプトを作成し、追加する前に必要なデータ属性をすべて設定します。

define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    var 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.appendChild(script);
  };
});

Adobe が推奨する text/x-magento-init の仕組みに従い、テンプレートから宣言的に初期化します。

html

<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

これにより、RequireJS の URL に認証情報を含めずに、最小構成と同じ SDK 要素を作成できます。オンラインストアのコードでは Publishable Key のみを使用してください。

選択したコンフィギュラブル商品の SKU#

標準のコンフィギュラブル商品ウィジェットは、Magento 独自のコンポーネントを通じて選択状態を公開しますが、テーマの上書きによってその構造は変わります。テーマがシンプル商品の ID を確定する箇所で、モジュール内に RequireJS のミックスインまたはリスナーを実装し、サーバーから渡された JSON で ID を対応する SKU に変換して、ホスト要素を置き換えます。

function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

  var container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = sku.trim();
  host.appendChild(container);
}

このミックスインと ID から SKU への対応データは、利用側で実装するアダプターです。選択肢のラベルから子商品の SKU を推測したり、公開 SDK 仕様に含まれない ideal.house のイベントやメソッドを記載したりしないでください。

動的コンテンツとキャッシュ#

スウォッチの変更、AJAX で読み込むおすすめ商品、クイックビュー、顧客ごとのコンテンツによってホスト要素が置き換わった後は、コンテナを再作成します。Magento の contentUpdated イベントは挿入されたコンテンツ内の Magento コンポーネントを初期化しますが、それ自体は選択中の SKU を提供しません。アダプターで正しいコードを特定して描画する必要があります。

コード変更後は環境に適したデプロイ手順を実行し、レイアウト、フルページ、ブロックのキャッシュを消去して静的コンテンツを再デプロイします。本番のバンドル化と圧縮、および Varnish/CDN を有効にしてテストしてください。

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

シンプル商品と子商品の SKUs を ideal.house の sku に対応付けます。商品アップロードと、インポート、ジョブの状態、一覧取得、更新、削除、再試行ガイドを使用します。Magento のエクスポート、管理用 API の呼び出し、cron ジョブ、Webhook は利用側のアダプターで実装します。

検証と削除#

シンプル商品、コンフィギュラブル商品、SKU がない商品、無効な子商品、不明な SKU のケースをテストします。SDK のリクエストが一回であること、スウォッチや選択肢を変えるたびに SKU が正確に対応すること、クイックビューとおすすめ商品で古い状態が残らないことを確認します。モバイル表示、キャッシュ利用時、顧客グループ別ページ、同意管理も確認してください。ソースや静的アセットに秘密の認証情報が含まれていないことを検証します。

削除するには、独自モジュールを無効化またはアンインストールするか、子テーマのレイアウト、テンプレート、RequireJS のファイルを削除します。静的コンテンツを再デプロイし、キャッシュを消去して、SDK の URL とコンテナがないことを確認します。