การเชื่อมต่อสำหรับผู้พัฒนา Shopify#
เพิ่มปุ่ม ideal.house ไปยังธีม Shopify และแมปเข้ากับ SKU ของตัวแปรสินค้าที่เลือก
<!-- DASHBOARD_READINESS -->ก่อนโหลด SDK: เปิด แดชบอร์ด → การตั้งค่า, เพิ่มต้นทางของหน้างานออนไลน์ของคุณไปยัง Allowed Origins (CORS) และคลิก บันทึก รวมชื่อโฮสต์ที่เผยแพร่และต้นทางใดๆ สำหรับพรีวิวหรือสเตจจิ้งที่คุณใช้; แยกต้นทางหลายรายการด้วยเครื่องหมายจุลภาค ดู ขั้นตอนการตั้งค่า
1. ยืนยันข้อกำหนดเบื้องต้น#
- คุณสามารถแก้ไขโค้ดธีมที่ใช้งานอยู่หรือสำเนาที่ปลอดภัยของธีมได้
- สินค้าทดสอบอย่างน้อยหนึ่งรายการถูกนำเข้าและใช้งานอยู่ในแคตตาล็อก
- SKU ของตัวแปรสินค้าที่เลือกคือ productCode ที่เก็บถาวรเดียวกันซึ่ง แค็ตตาล็อก ใช้สำหรับ Shop นี้
2. สร้างสเนปเล็ตปุ่ม#
snippets/idealhouse-view-button.liquid#
{%- comment -%}
Renders an ideal.house authored visualizer button.
Accepts:
- product_code: {String} Variant SKU used by the ideal.house Catalog mapping.
- placement: {String} "card", "pdp-desktop", or "pdp-mobile".
{%- endcomment -%}
{%- liquid
assign button_code = product_code | strip
assign button_placement = placement | default: 'card'
-%}
<button
type="button"
class="idealhouse-view-button idealhouse-view-button--{{ button_placement | escape }}"
data-idealhouse-authored-button
data-active="false"
{% if button_code != blank %}
data-product-code="{{ button_code | escape }}"
{% else %}
disabled
{% endif %}
style="visibility: hidden;"
>
<span>View in my room</span>
</button>
ซ่อนปุ่มไว้จนกว่า SDK จะยืนยันความเหมาะสมของสินค้า
3. เรนเดอร์ปุ่มบนพื้นผิวธีม#
การ์ดคอลเลกชันและการค้นหา#
{%- render 'idealhouse-view-button',
product_code: card_product.selected_or_first_available_variant.sku,
placement: 'card'
-%}
ไฟล์ทั่วไปรวมถึง snippets/card-product.liquid, snippets/product-card.liquid หรือ snippets/product-grid-item.liquid ปรับ card_product ให้เข้ากับตัวแปรสินค้าที่ธีมใช้
หน้ารายละเอียดสินค้า#
{%- render 'idealhouse-view-button',
product_code: product.selected_or_first_available_variant.sku,
placement: 'pdp-desktop'
-%}
{%- render 'idealhouse-view-button',
product_code: product.selected_or_first_available_variant.sku,
placement: 'pdp-mobile'
-%}
ไฟล์ทั่วไปรวมถึง sections/main-product.liquid หรือ snippets/product.liquid วางการเรนเดอร์ดิสก์ท็อปและมือถือแยกกันเฉพาะเมื่อธีมมีเลย์เอาต์แยกกัน
4. โหลด SDK และซิงค์ตัวแปร#
assets/idealhouse-room-visualizer.js#
(function () {
'use strict';
var buttonSelector = '[data-idealhouse-authored-button]';
var sdkRequested = false;
var buttonObserver = null;
function resetButton(button) {
button.dataset.active = 'false';
button.style.visibility = 'hidden';
delete button.dataset.rvProductCode;
delete button.dataset.rvProductType;
delete button.dataset.rvProductId;
delete button.dataset.rvProductIds;
}
function syncButton(button, productCode) {
if (!button) return false;
var code = typeof productCode === 'string' ? productCode.trim() : '';
resetButton(button);
delete button.dataset.productCode;
if (!code) {
button.disabled = true;
return false;
}
button.disabled = false;
button.dataset.productCode = code;
return true;
}
function syncButtons(container, productCode) {
(container || document).querySelectorAll(buttonSelector).forEach(function (button) {
syncButton(button, productCode);
});
}
function loadSdk() {
if (sdkRequested || !document.querySelector(buttonSelector)) return false;
sdkRequested = true;
if (buttonObserver) buttonObserver.disconnect();
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>';
script.dataset.authoredButtonSelector = buttonSelector;
document.head.appendChild(script);
return true;
}
function startSdkLoader() {
if (loadSdk() || typeof MutationObserver === 'undefined') return;
buttonObserver = new MutationObserver(loadSdk);
buttonObserver.observe(document.documentElement, { childList: true, subtree: true });
}
// Dispatch this event from your theme's variant-change callback.
document.addEventListener('idealhouse:variant-change', function (event) {
var detail = event.detail || {};
syncButtons(detail.container || document, event.detail && event.detail.sku);
});
window.IdealhouseShopify = {
syncButton: syncButton,
syncButtons: syncButtons
};
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', startSdkLoader);
} else {
startSdkLoader();
}
}());
Shopify ไม่ได้กำหนดเหตุการณ์ตัวแปรธีมสากลเพียงหนึ่งเดียว เชื่อมต่อตัวปรับเทียบขนาดเล็กด้านล่างเข้ากับเหตุการณ์หรือ ฟังก์ชันเรียกกลับ ที่ธีมที่ใช้งานอยู่เปิดเผย
ตัวอย่างอะแดปเตอร์เหตุการณ์ธีม#
แทนที่เหตุการณ์ตัวอย่างด้วย API ของธีมที่ใช้งานอยู่ ธีมบางตัวเผยแพร่ผ่าน window.subscribe; ตัวอื่นส่ง DOM เหตุการณ์หรืออัปเดต product-info
// Example only: replace "variant:change" with your theme's event.
document.addEventListener('variant:change', function (event) {
var variant = event.detail && event.detail.variant;
var productContainer = event.target.closest('product-info') || document;
document.dispatchEvent(new CustomEvent('idealhouse:variant-change', {
detail: {
container: productContainer,
sku: variant && variant.sku
}
}));
});
5. เพิ่มสไตล์ธีม#
assets/idealhouse-room-visualizer.css#
.idealhouse-view-button {
align-items: center;
justify-content: center;
width: 100%;
min-height: 44px;
padding: 0.75rem 1rem;
border: 1px solid currentColor;
border-radius: 6px;
background: transparent;
color: inherit;
cursor: pointer;
font: inherit;
}
.idealhouse-view-button[data-active="true"] {
display: inline-flex;
visibility: visible;
}
.idealhouse-view-button:disabled {
cursor: not-allowed;
opacity: 0.5;
}
ธีมอาจโอเวอร์ไรด์สไตล์ภาพเหล่านี้
6. รวมสินทรัพย์ใน theme.liquid#
รวมชีตสไตล์และสคริปต์ตัวแสดงภาพไว้ใน layout/theme.liquid เพื่อใช้สไตล์และเปิดใช้งานตัวโหลด SDK
รวมชีตสไตล์ (ภายใน <head>)#
{{ 'idealhouse-room-visualizer.css' | asset_url | stylesheet_tag }}
วางภายในแท็ก <head> ของ layout/theme.liquid เพื่อให้สไตล์โหลดได้อย่างสะอาด
รวมสคริปต์ (ก่อน </body>)#
<script src="{{ 'idealhouse-room-visualizer.js' | asset_url }}" defer="defer"></script>
ใช้ defer และวางก่อนแท็กปิด </body> ใน layout/theme.liquid เพื่อหลีกเลี่ยงการบล็อกการเรนเดอร์หน้า
ปุ่ม 'ดูในห้องของฉัน' จะยังคงซ่อนอยู่จนกว่าสคริปต์โหลดเดอร์นี้จะถูกรวมใน theme.liquid
7. ตรวจสอบบนหน้างานออนไลน์ที่ใช้งานอยู่#
- แผง Network แสดง sdk.js โหลดด้วย HTTP 200
- data-product-code ของปุ่มที่เขียนขึ้นตรงกับ productCode ของแคตตาล็อกอย่างถูกต้อง
- สินค้าที่เหมาะสมแสดงปุ่ม; สินค้าที่ไม่เหมาะสมยังคงซ่อนไว้
- การสลับตัวแปรสินค้าจะอัปเดต data-product-code และตรวจสอบความถูกต้องของปุ่มใหม่
- การวางตำแหน่งในคอลเลกชัน/การค้นหา, PDP เดสก์ท็อป และ PDP โมบาย ทำงานได้เมื่อมีอยู่
- การคลิกปุ่มเปิด ideal.house Viewer พร้อมสินค้าที่เลือก