การบูรณาการ Adobe Commerce / Magento Open Source#

ติดตั้ง Room Visualizer ผ่านโมดูล Magento หรือธีมแบบกำหนดเอง และแมป SKU ของสินค้าแบบง่ายที่แสดงไปยังแคตตาล็อกของ ideal.house

สถานะการตรวจสอบ: เอกสารฝั่งหน้าของ Adobe Commerce ได้รับการตรวจสอบเมื่อวันที่ 7 กันยายน 2569. ไม่มีระบบติดตั้งของร้านค้าให้ใช้งาน ธีม Luma/Blank, Hyvä, และ PWA Studio ใช้สแต็ก JavaScript ที่แตกต่างกัน ตัวอย่างเฉพาะด้านล่างมุ่งเน้นที่หน้างาน RequireJS มาตรฐาน

ก่อนโหลด SDK: เปิด แดชบอร์ด → การตั้งค่า, เพิ่มต้นทางของหน้าร้านออนไลน์ของคุณไปยัง Allowed Origins (CORS) และคลิก บันทึก รวมชื่อโฮสต์ที่เผยแพร่และต้นทางสำหรับดูตัวอย่างหรือทดสอบที่คุณใช้; แยกต้นทางหลายรายการด้วยเครื่องหมายจุลภาค ดู ขั้นตอนการตั้งค่า.

ข้อกำหนดเบื้องต้นและขอบเขต#

เตรียมอินสแตนซ์สำหรับพัฒนา, โมดูลแบบกำหนดเองหรือธีมลูก, การเข้าถึงการติดตั้ง, Shop ID, Publishable Key, และ SKU สำหรับทดสอบที่นำเข้าแล้ว ห้ามแก้ไขไฟล์ภายใต้ 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>

Product Code คือ sku ที่นำเข้าอย่างแม่นยำ ไม่ใช่ ID ของเอนทิตีตัวเลขของ Magento

เพิ่มบล็อกหน้าสินค้า#

สร้างโมดูลขนาดเล็กหรือการอัปเดตเลย์เอาต์ธีมสำหรับ 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);
  };
});

Initialize แบบ declarative จาก template โดยปฏิบัติตาม text/x-magento-init mechanism ที่ Adobe แนะนำ:

html

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

สิ่งนี้สร้างองค์ประกอบ SDK เดียวกับสัญญาขั้นต่ำ โดยไม่ต้องวางข้อมูลรับรองใน URL ของ RequireJS. ใช้เฉพาะ Publishable Key ในโค้ดหน้างาน

SKU ของสินค้าแบบกำหนดค่าที่เลือก#

วิดเจ็ตสินค้าแบบกำหนดค่ามาตรฐานจะเปิดเผยสถานะการเลือกผ่านคอมโพเนนต์ของ Magento เอง แต่การโอเวอร์ไรด์ธีมจะเปลี่ยนรูปแบบของมัน สร้าง mixin ของ RequireJS หรือตัวรับฟังเหตุการณ์ภายในโมดูลของคุณ ณ จุดที่ธีมแก้ไข ID ของสินค้าแบบเรียบง่าย, จับคู่ ID นั้นกับ SKU จาก JSON ที่เซิร์ฟเวอร์ให้มา, และแทนที่โฮสต์:

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 ของสินค้าย่อยจากป้ายชื่อตัวเลือก และห้ามระบุเหตุการณ์หรือเมธอด ideal.house ที่ไม่ได้อยู่ในข้อกำหนด SDK สาธารณะไว้ในเอกสาร

เนื้อหาไดนามิกและแคช#

สร้างคอนเทนเนอร์ใหม่หลังจากการเปลี่ยนแปลงสวอทช์, คำแนะนำที่โหลดผ่าน AJAX, การดูอย่างรวดเร็ว, หรือเนื้อหาเฉพาะลูกค้าแทนที่โฮสต์ของมัน เหตุการณ์ contentUpdated ของ Magento จะเริ่มต้นคอมโพเนนต์ Magento ในเนื้อหาที่ฉีดเข้ามา; มันไม่ได้ให้ SKU ที่เลือกแล้วโดยตัวมันเอง ดังนั้นตัวปรับเทียบของคุณจึงต้องแก้ไขและเรนเดอร์โค้ดที่ถูกต้องอยู่ดี

หลังแก้ไขโค้ด ให้ดำเนินขั้นตอนการติดตั้งใช้งานที่เหมาะกับสภาพแวดล้อม ล้างแคชผังหน้า/ทั้งหน้า/บล็อก และติดตั้งเนื้อหาคงที่ใหม่ ทดสอบโดยเปิดการรวมไฟล์และการย่อโค้ดสำหรับสภาพแวดล้อมจริง รวมถึง Varnish/CDN

นำเข้าข้อมูลสินค้า#

จับคู่ SKU ของสินค้าแบบเรียบง่ายและสินค้าลูกกับ ideal.house sku ใช้ การอัปโหลดสินค้า รวมถึง นำเข้า, สถานะงาน, ดูรายการ, การอัปเดต, การลบ, และ คำแนะนำในการลองใหม่ การส่งออก Magento, คำเรียก API จาก Admin, งาน cron, และ webhook เป็นตัวปรับเทียบของลูกค้า

ตรวจสอบและลบออก#

ทดสอบกรณีสินค้าแบบเรียบง่าย, สินค้าแบบกำหนดค่า, SKU ที่ขาดหาย, สินค้าลูกที่ถูกปิดใช้งาน, และ SKU ที่ไม่รู้จัก ตรวจสอบว่ามีคำขอ SDK เพียงหนึ่งครั้ง, การจับคู่ SKU ที่ถูกต้องแม่นยำหลังจากการเปลี่ยนแปลงสวอทช์/ตัวเลือกทุกครั้ง, พฤติกรรมที่สะอาดในการดูอย่างรวดเร็วและคำแนะนำ, เลย์เอาต์มือถือ, การเข้าถึงแคช, หน้ากลุ่มลูกค้า, และตัวควบคุมการยินยอม ตรวจสอบว่าไม่มีข้อมูลรับรองลับปรากฏในซอร์สโค้ดหรือสินทรัพย์แบบสถิต

เพื่อลบออก ให้ปิดใช้งาน/ถอนการติดตั้งโมดูลแบบกำหนดเอง หรือลบไฟล์ layout/template/RequireJS ของธีมลูก, จัดการเนื้อหาแบบสถิตใหม่, ล้างแคช, และตรวจสอบว่า SDK URL และคอนเทนเนอร์หายไป