Shoplazza 連携#

テーマアプリ拡張または独自の Liquid テーマを使って Shoplazza に Room Visualizer を追加し、選択中のバリエーションの SKU を ideal.house の商品コードとして描画します。

検証状況: 2026年9月7日 に Shoplazza のテーマ、拡張機能、商品、バリエーションのドキュメントを確認しました。パートナーアプリやマーチャントのテストストアは利用できなかったため、開発用ストアでインストールとバリエーション切り替えを検証する必要があります。

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

前提条件#

Shoplazza の開発用またはマーチャントのストア、テーマまたはアプリ拡張のソースへのアクセス、Shop ID、Publishable Key、対応するバリエーションの SKUs のインポート済みレコードを用意します。カスタマイズ前にマーチャントのテーマを複製してください。

テーマアプリ拡張は、保守しやすい再利用可能な方式です。アプリブロックは表示用 UI を挿入し、マーチャントが対応する商品セクションに追加する必要があります。アプリ埋め込みでは、サイト全体の動作を読み込めます。

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>

Shoplazza は variant.sku を公開しています。その正確な文字列を ideal.house の sku として使用します。

アプリブロックの追加#

商品セクション用のテーマ拡張のアプリブロックを作成します。商品コンテキスト内の Shoplazza の Liquid ブロックは、product にアクセスできます。最初はホスト要素を空にし、使用中のテーマの商品フォームの状態から選択中のバリエーションを渡します。

<div class="idealhouse-host"></div>

{% schema %}
{
  "name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
  "target": "section",
  "javascript": ["idealhouse.js"],
  "settings": []
}
{% endschema %}

バリエーションが一つの商品では、ブロックの JavaScript で、テーマが安全にシリアライズしたデータから product.variants の唯一の公開エントリーを読み取れます。複数のバリエーションがある場合は、テーマの既存の商品フォームで選択が確定するまでホスト要素を空にします。これにより、公開されていない選択中バリエーションの Liquid プロパティに依存せずに済みます。

SDK の読み込み#

idealhouse.js で SDK を一度だけ読み込みます。再利用可能なアプリでは、一つのマーチャントを固定で指定せず、サニタイズ済みの公開ブロックまたは埋め込み設定から Shop ID と Publishable Key を提供します。

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);
}

アプリのシークレットや ideal.house の Client Secret を公開してはいけません。

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

テーマの公開された商品フォームのコールバックを、このアダプターに接続します。

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

Shoplazza のバリエーションオブジェクトでは sku が公開されていますが、選択の実装はテーマごとに異なる場合があります。コールバックの接続は利用側のアダプターで行います。新たな選択の後はコンテナを再作成し、SDK が内容を追加したマークアップだけを変更する方法は避けてください。

コレクションのカード、クイックビュー、検索フィルター、クライアント側で描画するセクションでは、項目単位のホスト要素を追加し、テーマの公開された描画コールバック後に橋渡し処理を実行します。カード上で最終的なバリエーションが不明な場合は、ボタンを表示しないか、商品ページへのリンクを設置します。

商品のインポート#

対応するすべての variant.sku をエクスポートし、商品アップロードから ideal.house の sku としてインポートします。商品インポート、ジョブの状態、商品一覧、商品更新、商品削除、エラーと再試行を参照してください。

管理用 API のエクスポート、Webhook、定期同期、OAuth、拡張機能の配布は利用側で実装します。

検証と削除#

アプリブロックの配置、埋め込みの有効化、バリエーションが一つの商品、複数バリエーションのすべての選択肢、空・重複・不明な SKUs、コレクションのカード、クイックビュー、フィルター、ブラウザー履歴、モバイル、言語と通貨、同意管理、テーマのプレビューと公開モードをテストします。SDK のリクエストが一回で、バリエーションの SKU の対応付けが正確であることを確認します。

削除するには、テーマアプリ拡張を無効化してアンインストールするか、独自の Liquid と JavaScript を削除します。削除後のテーマを公開し、オンラインストアのキャッシュを消去して、SDK とすべての data-idealhouse-* ノードがないことを確認します。

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

• Shoplazza: テーマ拡張リファレンス
• Shoplazza: バリエーションの Liquid オブジェクト
• Shoplazza: 商品の Liquid オブジェクト
• Shoplazza: テーマのタグ