تكامل Shoplazza#
أضف Room Visualizer إلى Shoplazza باستخدام توسعة تطبيق القالب أو قالب Liquid مخصص، واعرض SKU لمتغير المنتج المحدد بوصفه Product Code في ideal.house.
حالة التحقق: تمت مراجعة وثائق سمة/توسعة/منتج/متغير Shoplazza في تاريخ 7 سبتمبر 2026. لم يكن هناك تطبيق شريك أو متجر اختبار للتاجر متاحًا، لذا يجب التحقق من التثبيت وانتقال المتغيرات في متجر تطوير.
قبل تحميل SDK: افتح لوحة التحكم ← الإعدادات، وأضف أصل واجهة متجرك إلى Allowed Origins (CORS)، ثم انقر على حفظ. أدرج اسم المضيف المنشور وأي أصول للمعاينة أو بيئة ما قبل الإنتاج تستخدمها؛ وافصل بين الأصول المتعددة بفواصل. راجع خطوات الإعداد.
المتطلبات المسبقة#
حضّر متجر Shoplazza تطوير/تاجر، وصولًا إلى مصدر السمة أو توسعة التطبيق، Shop ID، Publishable Key، وسجلات مستوردة لـ SKUs مدعومة للمتغيرات. انسخ سمة التاجر قبل التخصيص.
توسعة تطبيق السمة هي المسار القابل للصيانة والقابل لإعادة الاستخدام. تُحقن كتلة التطبيق واجهة مستخدم مرئية ويجب على التاجر إضافتها إلى قسم منتج متوافق؛ يمكن لتكامل التطبيق تحميل سلوك عالمي.
عقد 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>
توثّق Shoplazza الحقل variant.sku؛ استخدم السلسلة النصية نفسها تمامًا بوصفها sku في ideal.house.
أضف كتلة تطبيق#
أنشئ كتلة تطبيق توسعة السمة لقسم المنتج. يمكن لكتل Shoplazza Liquid في سياق المنتج الوصول إلى product. ابدأ بحاوية فارغة، ثم استخدم حالة نموذج المنتج للسمة النشطة لتوفير المتغير المحدد:
<div class="idealhouse-host"></div>
{% schema %}
{
"name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
"target": "section",
"javascript": ["idealhouse.js"],
"settings": []
}
{% endschema %}
بالنسبة لمنتج بمتغير واحد، يمكن لكتلة JavaScript قراءة الإدخال الوحيد الموثّق في product.variants من البيانات التي يتم تسلسلها بأمان من قبل السمة. بالنسبة لمتغيرات متعددة، احتفظ بالحاوية فارغة حتى يحل نموذج المنتج الموجود في السمة اختيارًا. يتجنب ذلك الاعتماد على خاصية Liquid لمتغير محدد غير موثّقة.
حمّل الـSDK#
في idealhouse.js، حمّل SDK مرة واحدة. لتطبيق قابل لإعادة الاستخدام، وفّر Shop ID وPublishable Key من خلال إعدادات عامة منقّاة للكتلة أو التضمين، بدلًا من تثبيت بيانات تاجر واحد داخل الشيفرة:
if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
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);
}
لا تعرض سر التطبيق أو ideal.house Client Secret أبدًا.
احتفظ بالمتغير المحدد متزامنًا#
اربط دالة رد النداء الموثقة لنموذج المنتج في القالب بهذا المحوّل:
function renderIdealhouseVariant(host, variant) {
host.replaceChildren();
const code = String(variant && variant.sku || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
يوثّق كائن متغير المنتج في Shoplazza الحقل sku، لكن القوالب قد تنفّذ الاختيار بطرق مختلفة. يقع ربط دالة رد النداء ضمن عمل المحوّل الذي ينفّذه العميل. أعد إنشاء الحاوية بعد اختيار جديد؛ ولا تكتفِ بتعديل الوسوم التي ملأها SDK.
لبطاقات المجموعات والعرض السريع ومرشحات البحث والأقسام المعروضة على جانب العميل، أضف عنصرًا حاويًا لكل عنصر، وشغّل دالة الربط بعد دالة رد النداء الموثقة لعرض القالب. إذا لم يُعرف متغير المنتج النهائي في بطاقة، فاحذف الزر أو أضف رابطًا إلى صفحة المنتج.
استيراد المنتجات#
تصدير كل variant.sku مدعوم واستيراده كـ ideal.house sku عبر رفع المنتجات. انظر استيراد المنتجات، حالة المهمة، قائمة المنتجات، تحديث المنتجات، حذف المنتج، والأخطاء وإعادة المحاولة.
ينفّذ العميل عمليات التصدير عبر Admin API، وإشعارات الويب، والمزامنة المجدولة، وOAuth، وتوزيع التوسعات.
التحقق والإزالة#
اختبر موضع كتلة التطبيق، وتمكين التضمين، ومنتجًا ذا متغير واحد، وجميع خيارات المنتجات متعددة المتغيرات، وقيم SKUs الفارغة أو المكررة أو غير المعروفة، وبطاقات المجموعات، والعرض السريع، والمرشحات، وسجل المتصفح، والهاتف المحمول، والتعريب والعملات، والموافقة، ووضعَي المعاينة والنشر الفعلي للقالب. تأكد من إرسال طلب SDK واحد ومن الربط الدقيق لقيمة SKU الخاصة بمتغير المنتج.
لإزالة التكامل،عطّل وأزل تثبيت توسعة تطبيق السمة أو أزل الـLiquid/JavaScript المخصصة، انشر السمة النظيفة، امسح ذاكرة التخزين المؤقت لواجهة المتجر، وتأكد من عدم وجود SDK وجميع عُقد data-idealhouse-*.