การเชื่อมต่อ WooCommerce#

เพิ่มปุ่ม Room Visualizer ในหน้าสินค้า WooCommerce และรักษาโค้ดสินค้า ideal.house ให้ซิงค์กับตัวแปร SKU ที่เลือก

สถานะการตรวจสอบ: เอกสารและพฤติกรรมสาธารณะของ WooCommerce ได้รับการทบทวนเมื่อ 7 กันยายน 2569 การใช้งานนี้ไม่ได้รับการรับรองในร้านค้าของลูกค้า เทมเพลตแบบคลาสสิก, ธีมแบบบล็อก, ส่วนขยาย variation และปลั๊กอิน มุมมองด่วน สามารถเรนเดอร์ DOM ได้ต่างกัน ให้ทดสอบ stack ที่คุณใช้จริงบน สภาพแวดล้อมทดสอบก่อนเผยแพร่

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

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

คู่มือนี้ออกแบบสำหรับ WooCommerce บน WordPress ใช้ปลั๊กอินเฉพาะไซต์ขนาดเล็กหรือธีมลูก, ตัวโหลดทรัพยากรมาตรฐานของ WordPress และ product ฮุก ของ WooCommerce ไม่ใช่ปลั๊กอิน ideal.house WordPress ที่ติดตั้งได้

เตรียมสิทธิ์ผู้ดูแลระบบและการเข้าถึงไฟล์, Shop ID, Publishable Key และบันทึก ideal.house ที่นำเข้าสำหรับ SKU ที่สามารถแสดงภาพได้ ให้สินค้าแบบเรียบง่ายทุกตัวและตัวแปรที่รองรับทุกตัวมี SKU ที่ไม่ว่างและไม่ซ้ำกันใน WooCommerce

มาร์กอัพ 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 ในแคตตาล็อกที่นำเข้า ห้ามใส่ ID ฐานข้อมูลของ WooCommerce ใน data-product-code เว้นแต่คุณจะใช้ ID เหล่านั้นเป็น SKU ของแคตตาล็อกอย่างตั้งใจ

โหลด SDK ครั้งเดียว#

เพิ่มโค้ดนี้ใน functions.php ของธีมลูกหรือปลั๊กอินเฉพาะไซต์ แทนที่ค่า placeholder

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

หากคุณรองรับเวอร์ชัน WooCommerce บน WordPress ก่อน 6.3 ให้ส่ง true เป็นอาร์กิวเมนต์ enqueue สุดท้าย และเพิ่ม async ในตัวกรอง

เรนเดอร์โฮสต์ของหน้าสินค้า#

ฮุก ต่อไปนี้จะวาง host หลังฟอร์มเพิ่มลงตะกร้า สินค้าแบบง่าย (Simple products) จะได้รับ SKU ทันที สินค้าแบบแปรผัน (Variable products) จะเริ่มว่างเปล่า ตัว adapter ในเบราว์เซอร์จะเติมข้อมูลเมื่อเลือก variation ครบถ้วน

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 หรือบล็อก Product Collection อาจต้องการการเชื่อมต่อแบบบล็อกหรือ ฮุก อื่นที่ระบุในเอกสารของ WooCommerce

ซิงค์ตัวแปรที่เลือก#

ฟอร์ม variation ที่รวมอยู่ใน WooCommerce จะเรียกเหตุการณ์วงจรชีวิต variation ของ jQuery เพิ่มไฟล์ท้องถิ่น เช่น assets/js/idealhouse-woocommerce.js, enqueue ด้วย dependencies 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);

ไฟล์นี้เป็น adapter ของ WooCommerce ที่ลูกค้าเป็นเจ้าของ หากปลั๊กอิน variation แทนที่สคริปต์ฟอร์มมาตรฐาน ให้ใช้ ฟังก์ชันเรียกกลับ การเลือกที่ระบุในเอกสารของปลั๊กอินนั้น แทนที่จะสมมติว่าเหตุการณ์เหล่านี้ยังทำงานอยู่ ห้ามอัปเดตเฉพาะแอตทริบิวต์ของคอนเทนเนอร์ที่ SDK ประมวลผลแล้ว ให้แทนที่ด้วยคอนเทนเนอร์ที่สะอาด

กริดสินค้า, quick view และการนำทางแบบ AJAX#

สำหรับการ์ดในแคตตาล็อก ให้ใช้ product-loop ฮุก เช่น woocommerce_after_shop_loop_item และเรนเดอร์ SKU ของสินค้าแบบง่าย สินค้าแบบแปรผันในกริดมักไม่มี variation ที่ถูก resolve ให้ลิงก์ไปยังหน้าสินค้าหรือสร้างตัว adapter เลือก variation ที่ชัดเจน

ปลั๊กอิน มุมมองด่วน และ WooCommerce Blocks สามารถแทรกสินค้าได้หลังโหลดหน้าแรก วาง host ในเทมเพลตที่เครื่องมือเหล่านั้นเรนเดอร์ และรัน bridge render() ของคุณจาก ฟังก์ชันเรียกกลับ การเสร็จสิ้นที่ระบุในเอกสารของเครื่องมือนั้น หากไม่มี ฟังก์ชันเรียกกลับ ที่เสถียร MutationObserver แบบ scoped อาจตรวจจับโหนด .idealhouse-host ใหม่ได้ แต่ลูกค้าต้องรับผิดชอบประสิทธิภาพและวงจรชีวิตของมัน

การแมปและนำเข้าแคตตาล็อก#

แมพ WC_Product::get_sku() และแต่ละ WC_Product_Variation::get_sku() ไปยัง ideal.house sku สินค้าแม่และสินค้าลูกไม่ควรใช้รหัสเดียวกันหากพวกมันแทนที่สินทรัพย์ภาพที่แตกต่างกัน

WooCommerce ไม่ส่งการเปลี่ยนแปลงแคตตาล็อกไปยัง ideal.house อัตโนมัติ ใช้ การอัปโหลดสินค้า และคู่มือสำหรับ นำเข้า, สถานะงาน, ดูรายการ, การอัปเดต, การลบ และ การจัดการการลองใหม่ การส่งออกตามกำหนดเวลาหรือ webhook bridge เป็นหน้าที่การ implement ของลูกค้า

ตรวจสอบก่อนเปิดตัว#

1. ทดสอบสินค้าแบบเรียบง่ายหนึ่งตัว, สินค้าแบบตัวแปรหนึ่งตัว, SKU ที่ขาดหายหนึ่งรายการ และ SKU ที่ไม่มีใน ideal.house
2. ยืนยันว่า SDK ถูกเรียกขอเพียงครั้งเดียวและแท็กสคริปต์ของมันยังคงมีแอตทริบิวต์ข้อมูลรับรองทั้งสอง
3. เลือกตัวแปรทั้งหมดและยืนยันว่า data-product-code เท่ากับ SKU ของตัวแปร
4. รีเซ็ตฟอร์มตัวแปร; คอนเทนเนอร์เก่าควรหายไป
5. ทดสอบกริดสินค้า, quick view, ตัวกรอง AJAX, cart fragments, ปุ่มเพิ่มลงตะกร้าแบบ sticky บนมือถือ และการย้อนกลับ/ไปข้างหน้าของเบราว์เซอร์ หากเหมาะสม
6. ทดสอบในสถานะที่ไม่ได้เข้าสู่ระบบ พร้อมการควบคุมการยินยอม (consent) และเปิดแคชแบบ production
7. ตรวจสอบว่า Client Secret ไม่ปรากฏใน HTML, JavaScript, log หรือ source maps

ลบการเชื่อมต่อ#

ลบ ฮุก/filter ของ PHP และ enqueue ของ adapter variation ท้องถิ่น ลบ host ออกจากเทมเพลตหรือบล็อกที่ถูก override ล้าง transients ของ WooCommerce และแคชหน้า/CDN จากนั้นยืนยันว่าไม่มีคำขอ SDK หรือองค์ประกอบ data-idealhouse-* เหลืออยู่

แหล่งอ้างอิงแพลตฟอร์มอย่างเป็นทางการ#

• WordPress ธีม Handbook: Including ทรัพยากร
• WooCommerce: แนวทางปฏิบัติที่ดีในการพัฒนาส่วนขยาย
• โครงสร้างเทมเพลตของ WooCommerce
• ข้อมูลสินค้าแบบตัวแปรในฟอร์มตัวแปรหลักของ WooCommerce