WooCommerce 連携#

WooCommerce の商品ページに Room Visualizer ボタンを追加し、ideal.house の商品コードを選択中のバリエーションの SKU と同期させます。

検証状況: 2026年9月7日 にドキュメントと公開されている WooCommerce の動作を確認しました。この実装は顧客のストアで認証済みではありません。クラシックテンプレート、ブロックテーマ、バリエーション拡張、クイックビュープラグインでは、描画される DOM が異なる場合があります。実際に使う構成をステージング環境でテストしてください。

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

対応範囲と前提条件#

このガイドは WordPress 上の WooCommerce を対象とします。サイト専用の小さなプラグインまたは子テーマ、標準の WordPress アセットローダー、WooCommerce の商品フックを使用します。インストール可能な ideal.house の WordPress プラグインではありません。

管理者権限とファイルへのアクセス、Shop ID、Publishable Key、可視化する各 SKU に対応するインポート済みの ideal.house レコードを用意します。WooCommerce で、すべてのシンプル商品と対応する各バリエーションに、空でない一意の SKU を設定してください。

SDK の最小マークアップ#

この連携では、次の公開 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 と一致する必要があります。カタログの SKUs として意図的に使用した場合を除き、WooCommerce のデータベース ID を data-product-code に設定しないでください。

SDK を一度だけ読み込む#

このコードを子テーマの functions.php またはサイト専用プラグインに追加し、プレースホルダーを置き換えます。

add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') return $tag;

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

6.3 より前の WordPress 上で動作する WooCommerce のバージョンに対応する場合は、読み込み登録の最後の引数に true を渡し、フィルター内で async を追加します。

商品ページのホスト要素の描画#

次のフックは、カート追加フォームの後にホスト要素を配置します。シンプル商品には直ちに SKU を設定します。バリエーション商品では最初は空にし、完全なバリエーションが選択されるとブラウザー側のアダプターが値を設定します。

add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

商品テンプレートにこのフックがあることを確認します。WooCommerce のテンプレートや商品コレクションブロックを置き換えるテーマでは、ブロック連携または別の公開された WooCommerce フックが必要になる場合があります。

選択したバリエーションの同期#

WooCommerce に同梱されたバリエーションフォームは、jQuery のバリエーションライフサイクルイベントを発行します。例えば assets/js/idealhouse-woocommerce.js というローカルファイルを追加し、jquery と wc-add-to-cart-variation を依存関係として読み込み登録したうえで、以下を使用します。

(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

このファイルは利用側で管理する WooCommerce アダプターです。バリエーションプラグインが標準フォームのスクリプトを置き換える場合は、同じイベントが引き続き発火すると仮定せず、そのプラグインで公開されている選択コールバックを使用します。SDK が処理済みのコンテナの属性だけを更新せず、新しいコンテナに置き換えてください。

商品グリッド、クイックビュー、AJAX による画面遷移#

カタログのカードでは、woocommerce_after_shop_loop_item などの商品ループフックを使用し、シンプル商品の SKU を描画します。グリッド上のバリエーション商品では、通常バリエーションが未確定です。商品ページへのリンクを設置するか、明示的なバリエーション選択アダプターを作成してください。

クイックビュープラグインや WooCommerce のブロックは、初回のページ読み込み後に商品を挿入できます。それらが描画するテンプレート内にホスト要素を配置し、ツールの公開された完了コールバックから render() の橋渡し処理を実行します。安定したコールバックがない場合は、監視範囲を限定した MutationObserver で新しい .idealhouse-host ノードを検出できますが、性能とライフサイクルは利用側で管理します。

カタログの対応付けとインポート#

WC_Product::get_sku() と各 WC_Product_Variation::get_sku() を ideal.house の sku に対応付けます。異なる可視化アセットを表す親商品と子商品で、同じコードを共有してはいけません。

WooCommerce はカタログの変更を ideal.house に自動送信しません。商品アップロードと、インポート、ジョブの状態、一覧取得、更新、削除、再試行処理のガイドを使用します。定期エクスポートや Webhook の橋渡しは利用側で実装します。

公開前の検証#

1. シンプル商品、バリエーション商品、SKU がない商品、ideal.house に存在しない SKU の商品を一つずつテストします。
2. SDK のリクエストが一回だけで、スクリプトタグに両方の認証属性が保持されていることを確認します。
3. すべてのバリエーションを選択し、data-product-code がバリエーションの SKU と一致することを確認します。
4. バリエーションフォームをリセットし、古いコンテナが消えることを確認します。
5. 使用している機能に応じて、商品グリッド、クイックビュー、AJAX フィルター、カートフラグメント、モバイルの固定カート追加ボタン、ブラウザーの戻る・進むをテストします。
6. ログアウトした状態で、同意管理と本番用キャッシュを有効にしてテストします。
7. HTML、JavaScript、ログ、ソースマップに Client Secret が含まれていないことを確認します。

連携の削除#

PHP のフックとフィルター、およびローカルのバリエーションアダプターの読み込み登録を削除します。上書きしたテンプレートやブロックからホスト要素を削除し、WooCommerce のトランジェントとページ/CDN キャッシュを消去します。SDK のリクエストや data-idealhouse-* 要素が残っていないことを確認してください。

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

• WordPress テーマハンドブック: アセットの読み込み
• WooCommerce 拡張機能開発の推奨事項
• WooCommerce のテンプレート構造
• WooCommerce の標準バリエーションフォームにおけるバリエーション商品データ