Ideal House
تخطّي إلى المحتوى

تكامل Ecwid#

استخدم تطبيق واجهة متجر مخصص من Ecwid ودورة حياة Storefront JS API موثّقة لإضافة عناصر تحكم Room Visualizer إلى صفحات منتج Ecwid.

حالة التحقق: تمت مراجعة وثائق Storefront JS Ecwid API في تاريخ 7 سبتمبر 2026. لم يكن هناك تطبيق Ecwid أو متجر اختبار للتاجر متاحًا. يجب تأكيد حقول حمولة الصفحة بدقة بالرجوع إلى مرجع OnPageLoaded الحالي قبل النشر.

قبل تحميل SDK: افتح لوحة التحكم ← الإعدادات، وأضف أصل واجهة متجرك إلى Allowed Origins (CORS)، ثم انقر على حفظ. أدرج اسم المضيف المنشور وأي أصول للمعاينة أو بيئة ما قبل الإنتاج تستخدمها؛ وافصل بين الأصول المتعددة بفواصل. راجع خطوات الإعداد.

المتطلبات السابقة والمسار المدعوم#

يتطلب Ecwid تطبيقًا مخصصًا بملف JavaScript مستضاف ذاتيًا لتخصيص واجهة المتجر بصورة مستدامة. جهّز متجر تطوير وتطبيقًا في Ecwid، وملف محوّل مستضافًا عبر HTTPS، وShop ID، وPublishable Key، وقيم SKUs مستوردة للمنتجات ومتغيراتها.

إذا تم تضمين Ecwid في CMS آخر، يظل تطبيق واجهة المتجر المخصصة هو المكان الموثوق للكود لأنه يعمل مع واجهة متجر Ecwid. قد لا يشارك سكربت الصفحة الأم نفس دورة الحياة أو المستند في كل وضع تضمين.

عقد 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>

استخدم Ecwid SKU الدقيق الذي استوردته بوصفه ideal.house sku.

تهيئة تطبيق واجهة المتجر Ecwid#

اتبع دليل البدء السريع لتخصيص واجهة متجر Ecwid لتسجيل الملف المستضاف ذاتيًا. ابدأ تشغيله باستخدام دالة رد النداء الموثقة عند جاهزية API، ثم حمّل SDK الخاص بـ ideal.house مرة واحدة:

js
Ecwid.OnAPILoaded.add(function () {
  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);
});

لتطبيق متعدد المتاجر، احصل على القيمتين العامة ideal.house من إعدادات التطبيق العامة الآمنة. لا تضع سر تطبيق Ecwid، رمز الوصول، أو ideal.house Client Secret في هذا الملف.

عرض على صفحات المنتج#

يُوثّق Ecwid Ecwid.OnPageLoaded.add() ويوفر معلومات الصفحة لرد اتصالها. استخدم مرجع API الحالي لتأكيد نوع ومعرف صفحة المنتج، استرجاع أو قراءة بيانات المنتج من خلال واجهة عميل Ecwid المدعومة، ثم تمرير SKU الذي جرى تحديده إلى:

js
function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

أدرج host في موضع ثابت ضمن تفاصيل المنتج بعد أن ينتهي Ecwid من عرض الصفحة. أزل العنصر الحاوي السابق عند تغيّر نوع الصفحة. يتولى العميل تنفيذ محدد DOM ومنطق العثور على المنتج من بيانات الصفحة ضمن المحوّل، لأن تخطيطات واجهة متجر Ecwid وإصدارات بيانات الصفحة قد تتغير.

الخيارات والتنقل#

عندما يختار المشتري خيارات المنتج، انتظر حتى يحدّد Ecwid متغير المنتج القابل للشراء وSKU الخاص بها. استدعِ mountIdealhouse() مع ذلك SKU، أو امسح الحاوية إذا كان الاختيار غير مكتمل. لا تقم بربط تسميات الخيارات لتصنيع رمز.

Ecwid واجهة متجر ذات صفحة واحدة. استخدم دورة حياة الصفحة الموثقة (OnPageLoaded ودوال رد النداء لتبديل الصفحات)، بدلًا من الاكتفاء بالاستماع إلى حدث DOMContentLoaded في المتصفح. عند التنقل بين الفئات ونتائج البحث، واستخدام زري الرجوع والتقدم في المتصفح، والأدوات المضمّنة، والنوافذ المنبثقة للمنتجات، يجب إزالة العناصر الحاوية القديمة للمنتجات وتركيب حاوية جديدة بعد العرض.

استيراد المنتجات#

صدّر حقول SKU للمنتجات ومتغيراتها في Ecwid واربطها إلى ideal.house sku. استخدم رفع المنتج، بما في ذلك استيراد المنتجات، حالة المهمة، قائمة المنتجات، تحديث المنتجات، حذف المنتج، والأخطاء وإعادة المحاولة.

يتولى العميل أي تصدير عبر Ecwid REST API، أو إشعارات ويب، أو تثبيت باستخدام OAuth، أو مزامنة متكررة، ويجب تنفيذ ذلك على الخادم مع التفويض المناسب من Ecwid.

التحقق والإزالة#

اختبر تثبيت التطبيق، وتهيئة API، والانتقال بين المنتجات والفئات والبحث، وكل متغير منتج، وقيم SKUs المفقودة وغير المعروفة، وزري الرجوع والتقدم في المتصفح، وأداة Ecwid مضمّنة في موقع آخر، وتخطيط الهاتف المحمول، والموافقة، وحالتي تسجيل دخول العملاء وخروجهم. تأكد من إرسال طلب SDK واحد في المستند الذي يحتوي على العنصر الحاوي، ومن التطابق التام لقيمة SKU.

للإزالة، افصل ملف JavaScript المضيف ذاتيًا عن التطبيق المخصص أو قم بإلغاء تثبيت التطبيق، وأزل العناصر الحاوية ومستمعات الأحداث المضافة، ثم أكد زوال SDK URL وجميع عقد data-idealhouse-* بعد تصفح واجهة المتجر وإعادة تحميل قاسية.

مراجع المنصة الرسمية#