การบูรณาการ BigCommerce#

เพิ่ม Room Visualizer ไปยังหน้างาน Stencil ของ BigCommerce โดยโหลด SDK เพียงครั้งเดียวและเรนเดอร์ SKU ของสินค้าหรือตัวแปรสินค้าปัจจุบันลงในคอนเทนเนอร์ของปุ่มที่สร้างอัตโนมัติ

สถานะการตรวจสอบ: เอกสารสำหรับนักพัฒนา BigCommerce ได้รับการตรวจสอบเมื่อ 7 กันยายน 2569. ไม่มีร้านค้าทดสอบให้ใช้งาน Stencil และ Catalyst มีโมเดลการเรนเดอร์และการนำทางที่แตกต่างกัน คู่มือนี้ให้แนวทาง Stencil ที่สามารถดำเนินการได้ และแนะนำหน้าร้าน Catalyst ให้ใช้ตัวปรับเทียบเฟรมเวิร์ก

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

เลือกเส้นทางหน้างาน#

Stencil: ติดตั้ง loader ด้วย Script Manager หรือ Scripts API จากนั้นเพิ่มคอนเทนเนอร์ใน custom ธีม template
Catalyst: เพิ่มสคริปต์และคอมโพเนนต์ในแอป React/Next.js ของ Catalyst; ทำตาม React / Next.js.
Legacy Blueprint: ย้ายไปยัง หน้าร้านออนไลน์ ที่รองรับหรือให้ BigCommerce developer ระบุจุดแทรกที่ปลอดภัย เอกสาร Scripts API ปัจจุบันจัดการ Blueprint แยกต่างหาก

คุณต้องมีสิทธิ์แก้ไขธีม, ธีม/ช่องสำหรับทดสอบ, ideal.house Shop ID และ Publishable Key และ BigCommerce SKU อย่างน้อยหนึ่งรายการที่นำเข้า ideal.house แล้ว

สัญญา 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 ของแคตตาล็อกที่นำเข้าอย่างแม่นยำ คู่มือนี้ไม่ได้สมมติว่ามีแอป ideal.house BigCommerce

ติดตั้งบน Stencil#

ใน หน้าร้านออนไลน์ → ตัวจัดการสคริปต์ ให้สร้างสคริปต์ส่วนท้ายสำหรับหน้าร้าน/ช่องทางและหน้าสินค้าที่เกี่ยวข้อง วางเฉพาะแท็กสคริปต์ SDK จากตัวอย่างพร้อมข้อมูลรับรองที่ใช้ในเบราว์เซอร์ได้อย่างปลอดภัย ตัวจัดการสคริปต์เป็นเครื่องมือในแผงควบคุมที่ทำหน้าที่สอดคล้องกับ Scripts API ซึ่งรองรับการระบุช่องทาง

สำหรับแอปที่นำกลับมาใช้ใหม่ได้ ให้ใช้ Scripts API ของ BigCommerce แทน การดำเนินการ API ดังกล่าวและขั้นตอน OAuth ของแอปเป็นความรับผิดชอบของบริการเชื่อมต่อระบบของคุณ ห้ามเปิดเผยโทเคนเข้าถึงในโค้ดหน้าร้าน

ยืนยันว่ามีแท็ก SDK เพียงหนึ่งรายการเท่านั้น อย่ารวมไว้ใน templates/layout/base.html ด้วย

เรนเดอร์สินค้าเริ่มต้น#

ในธีม Stencil ที่กำหนดเอง ให้เพิ่มคอนเทนเนอร์ใกล้แบบฟอร์มสินค้าในส่วนย่อยของเทมเพลตแสดงสินค้าที่ธีมของคุณใช้:

handlebars

{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

ส่วนย่อยของเทมเพลตที่ต้องใช้แตกต่างกันตามธีม ใช้ Stencil CLI เพื่อดูตัวอย่างธีมที่ปรับแต่งแล้ว และเก็บการเปลี่ยนแปลงไว้ในธีมที่อยู่ภายใต้การควบคุมเวอร์ชัน แทนการแก้ไข HTML ของหน้าร้านที่สร้างขึ้นโดยอัตโนมัติ

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

ซิงค์ตัวเลือกสินค้า#

JavaScript ของธีม Stencil รับการเปลี่ยนแปลงตัวเลือกสินค้าผ่านโค้ดรายละเอียดสินค้าที่เฉพาะเจาะจงกับธีม ให้เพิ่มโค้ดเชื่อมต่อที่ลูกค้าพัฒนาตรงจุดที่ธีมปัจจุบันระบุผลตอบกลับของตัวเลือกสินค้าที่เลือกครบแล้ว:

export function replaceIdealhouseContainer(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);
}

ส่ง SKU ของตัวเลือกสินค้าที่ระบบระบุได้แล้วจากฟังก์ชันเรียกกลับของธีม ธีม BigCommerce สามารถปรับแต่งหรือแทนที่การทำงานเริ่มต้นของส่วนรายละเอียดสินค้าได้ คู่มือนี้จึงไม่กำหนดเหตุการณ์เปลี่ยนตัวเลือกส่วนกลางขึ้นเอง ลบคอนเทนเนอร์เก่าก่อนแทรกคอนเทนเนอร์ใหม่

Quick view และ dynamic pages#

การดูอย่างรวดเร็ว, การค้นหาแบบแยกfacet, การแบ่งหน้า, และการนำทางฝั่งไคลเอนต์ สามารถแทนที่ DOM ของสินค้าได้ เพิ่มคอนเทนเนอร์ที่สะอาดในเทมเพลตที่เรนเดอร์ทุกตัว และเรียกใช้ bridge เดียวกันหลังจาก ฟังก์ชันเรียกกลับ การเรนเดอร์ที่มีเอกสารรองรับของธีม ห้ามโคลนคอนเทนเนอร์ที่ SDK เติมข้อมูลไว้แล้ว

Catalyst ใช้ ฝั่งไคลเอนต์ React rendering และไม่มี Stencil Handlebars context โหลด SDK ครั้งเดียวใน แอป shell และกำหนด visualizer component ตาม SKU ของ variant ที่เลือกตามที่แสดงใน React/Next.js guide

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

แมปค่า sku ของ BigCommerce ไปยัง sku ของ ideal.house; สำหรับตัวแปรสินค้า ให้ใช้ SKU ของแต่ละตัวแปรสินค้าแทน ID ของสินค้าแม่ ข้อมูลแคตตาล็อกของ BigCommerce ไม่ได้รับการซิงค์โดย SDK ฝั่งเบราว์เซอร์

ใช้ การอัปโหลดสินค้า สำหรับสัญญาการนำเข้าที่ได้รับการอนุมัติ จากนั้นตรวจสอบ นำเข้าสินค้า, สถานะงาน, ดูรายการสินค้า, อัปเดตสินค้า, ลบสินค้า, และ ข้อผิดพลาดและการลองใหม่. การส่งออก API ของ BigCommerce, webhook หรือการซิงค์ตามตารางเวลา เป็นตัวปรับเทียบที่ลูกค้าดำเนินการ

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

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

หากต้องการลบการเชื่อมต่อ ให้ลบรายการในตัวจัดการสคริปต์หรือระเบียน Scripts API ลบมาร์กอัปคอนเทนเนอร์และโค้ดเชื่อมต่อทั้งหมดจากธีม เผยแพร่ธีมที่ทำความสะอาดแล้ว จากนั้นล้างแคชหน้าร้าน/CDN ยืนยันว่าไม่มีคำขอ SDK ในทุกช่องทาง