تكامل مطوّر Shopify#
أضف زر ideal.house إلى قالب Shopify واربطه بقيمة SKU لمتغير المنتج المحدد.
<!-- DASHBOARD_READINESS -->قبل تحميل SDK: افتح لوحة التحكم ← الإعدادات، وأضف أصل واجهة متجرك إلى Allowed Origins (CORS)، ثم انقر على حفظ. أدرج اسم المضيف المنشور وأي أصول للمعاينة أو بيئة ما قبل الإنتاج تستخدمها؛ وافصل بين الأصول المتعددة بفواصل. راجع خطوات الإعداد.
1. تأكيد المتطلبات السابقة#
- يمكنك تعديل رمز السمة الحيّة أو نسخة آمنة من السمة.
- تم استيراد منتج اختباري واحد على الأقل وتفعيله في الكتالوج.
- قيمة SKU لمتغير المنتج المحدد هي قيمة productCode المحفوظة نفسها التي يستخدمها الكتالوج لهذا المتجر.
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. التحقق في واجهة المتجر الحيّة#
- تُظهر لوحة الشبكة أن sdk.js تم تحميله مع HTTP 200.
- تطابق قيمة data-product-code للزر المُنشأ يدويًا قيمة productCode في الكتالوج تمامًا.
- المنتجات المؤهلة تظهر زرًا؛ والمنتجات غير المؤهلة تحتفظ بإخفائه.
- يؤدي تغيير متغير المنتج إلى تحديث data-product-code وإعادة التحقق من صلاحية الزر.
- تعمل أماكن بطاقات المجموعة/البحث، وصفحة PDP لسطح المكتب، وصفحة PDP للهاتف المحمول حيثما تكون موجودة.
- يؤدي النقر على الزر إلى فتح ideal.house Viewer مع المنتج المحدد.