การเชื่อมต่อ React / Next.js#

ใช้ ideal.house เบราว์เซอร์ SDK โดยตรงใน React หรือ Next.js ไม่มีแพ็กเกจ npm แยกสำหรับ ideal.house React ในคู่มือนี้

สถานะการตรวจสอบ: มาร์กอัพ SDK ได้รับการตรวจสอบเทียบกับเทมเพลตแดชบอร์ดปัจจุบัน; เอกสารวงจรชีวิต/สคริปต์อย่างเป็นทางการของ React และ Next.js ได้รับการตรวจสอบเมื่อ 7 กันยายน 2569 ไม่มีแอปพลิเคชันของลูกค้าหรือข้อมูลรับรองการผลิตให้ใช้งาน จึงต้องตรวจสอบแอปพลิเคชันที่สร้างเสร็จแล้วแบบครบวงจร

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

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

เตรียม Shop ID, Publishable Key, แคตตาล็อก SKU ที่นำเข้าแล้ว และค่าสินค้า/ตัวแปรที่เรนเดอร์ด้วยไคลเอนต์ Publishable Key อาจปรากฏในมาร์กอัพเบราว์เซอร์ เก็บ Client Secrets, คีย์ AI API และข้อมูลรับรองการนำเข้าสินค้าส่วนตัวใดๆ ไว้บนเซิร์ฟเวอร์

SDK ค้นหาคอนเทนเนอร์ DOM React เป็นเจ้าของเวลาติดตั้งโหนดเหล่านั้น; การเชื่อมต่อของคุณเป็นเจ้าของการแก้ไขตัวแปรปัจจุบันและการแทนที่คอนเทนเนอร์เมื่อ SKU เปลี่ยน

สัญญา 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>

data-product-code ต้องเท่ากับ ideal.house แคตตาล็อก sku อย่างถูกต้อง

คอมโพเนนต์ React#

ติดตั้งคอนเทนเนอร์ใหม่ทุกครั้งเมื่อรหัสสินค้าเปลี่ยน key บังคับให้ React แทนที่โหนด DOM แทนที่จะใช้คอนเทนเนอร์ที่ SDK อาจเติมข้อมูลไว้แล้ว:

tsx

type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

ส่ง SKU ของตัวแปรสินค้าที่เลือก ไม่ใช่ชื่อสินค้า สแลกรูต ID ฐานข้อมูล หรือป้ายชื่อตัวเลือก หากการเลือกไม่สมบูรณ์ ให้เรนเดอร์ null

โหลดเดอร์ Next.js แอป Router#

วาง SDK เพียงครั้งเดียวในเลย์เอาต์ร่วมที่แคบที่สุดที่ครอบคลุมหน้าสินค้า Next.js ระบุ afterInteractive สำหรับสคริปต์ที่โหลดหลังการไฮเดรชันบางส่วน:

tsx

import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

เรนเดอร์ IdealhouseSdk เพียงครั้งเดียวจากเลย์เอาต์ จากนั้นเรนเดอร์ RoomVisualizerButton ภายในคอมโพเนนต์ไคลเอนต์ที่เป็นเจ้าของการเลือกตัวแปร ค่าที่มีคำนำหน้า NEXT_PUBLIC_ จะถูกส่งไปยังเบราว์เซอร์; ใช้เฉพาะสำหรับ Shop ID และ Publishable Key

สำหรับ Pages Router หรือ React แบบธรรมดา สร้างสคริปต์เพียงครั้งเดียวในเปลือก HTML หรือใช้เอฟเฟกต์ระดับบนสุดเพียงหนึ่ง:

tsx

useEffect(() => {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;
  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);
}, []);

Strict Mode ของ React ดำเนินรอบการตั้งค่าการพัฒนาเพิ่มเติมอย่างตั้งใจ ดังนั้นการตรวจสอบซ้ำจึงจำเป็น อย่าลบแท็ก SDK ที่ใช้ร่วมกันเมื่อคอมโพเนนต์สินค้ารายบุคคลถูก unmount

การนำทาง, รายการ และตัวแปร#

การเปลี่ยนเส้นทางฝั่งไคลเอนต์จะไม่โหลดสคริปต์เลย์เอาต์ใหม่ กำหนด key ให้แต่ละการควบคุมสินค้าด้วยเอกลักษณ์เส้นทางที่มั่นคงร่วมกับ SKU หาก SKU เดียวกันสามารถปรากฏในมุมมองที่ติดตั้งพร้อมกันหลายมุมมอง สำหรับกริด ทุกการ์ดต้องมี SKU ของตัวเอง เมื่อการเลื่อนแบบไม่สิ้นสุดเพิ่มการ์ด React จะติดตั้งคอนเทนเนอร์ใหม่ที่ไม่สะอาดโดยธรรมชาติ

สำหรับการเลือกตัวแปรสินค้า ให้คำนวณ selectedVariant.sku จากสถานะพาณิชย์ของคุณและส่งเป็น productCode อย่าเรียกวิธีการรีเฟรช SDK ที่ไม่มีเอกสารระบุไว้ ลิ้นชักดูแบบด่วนและการเปลี่ยนเส้นทางควร unmount คอมโพเนนต์ก่อนหน้าเพื่อให้ DOM ที่ประมวลผลแล้วไม่รั่วไหลไปยังสินค้าถัดไป

หากการไฮเดรชันของ React รายงานความไม่ตรงกัน ให้แน่ใจว่าการเรนเดอร์เซิร์ฟเวอร์และการเรนเดอร์ไคลเอนต์ครั้งแรกตรงกัน การไม่เรนเดอร์คอนเทนเนอร์จนกว่าสถานะพาณิชย์ของไคลเอนต์จะแก้ไข SKU แล้วถือว่าถูกต้อง

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

แมป SKU ตัวแปรมาตรฐานของระบบหลังบ้านพาณิชย์ไปยัง ideal.house sku ใช้ การอัปโหลดสินค้า, จากนั้นดู นำเข้าสินค้า, สถานะงาน, ดูรายการสินค้า, อัปเดตสินค้า, ลบสินค้า, และ ข้อผิดพลาดและการลองใหม่

การสอบถามแคตตาล็อกหลังบ้าน, เว็บฮุค, ซิงค์ตามกำหนดเวลา หรือบริการโทเคนเริ่มต้นยังคงเป็นโค้ดแอปพลิเคชัน; เบราว์เซอร์ SDK ไม่ได้จัดหาสิ่งเหล่านี้

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

ทดสอบการเรนเดอร์/ไฮเดรชันฝั่งเซิร์ฟเวอร์ การโหลดแบบแข็ง การนำทางฝั่งไคลเอนต์ การย้อนกลับ/ไปข้างหน้าของเบราว์เซอร์ การเปลี่ยนตัวแปรสินค้า SKU ที่ว่างเปล่า/ไม่รู้จัก การ์ดซ้ำ การดูแบบด่วน สถานะ Suspense/โหลด โมบาย การควบคุมการยินยอม และการสร้างแบบผลิต ยืนยันคำขอ SDK หนึ่งครั้งและความเท่ากันของรหัสสินค้า DOM/SKU ที่ถูกต้อง ตรวจสอบ bundle ฝั่งไคลเอนต์ที่สร้างแล้วว่ามีข้อมูลลับที่รั่วไหลหรือไม่

เพื่อลบ ให้ลบคอมโพเนนต์/แท็ก SDK ที่ใช้ร่วมกันและการใช้งาน RoomVisualizerButton ทั้งหมด ลบตัวแปรสภาพแวดล้อมสาธารณะสองตัว สร้างใหม่ และตรวจสอบว่าไม่มี SDK URL หรือมาร์กอัป data-idealhouse-* เหลืออยู่