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

تكامل BigCommerce#

أضف Room Visualizer إلى متجر BigCommerce Stencil عن طريق تحميل SDK مرة واحدة وعرض SKU المنتج أو النوع الحالي في حاوية زر تم إنشاؤها.

حالة التحقق: تم مراجعة توثيق المطورين الخاص بـ BigCommerce في 7 سبتمبر 2026. لم يتوفر متجر اختبار. تختلف نماذج العرض والتنقل بين Stencil وCatalyst؛ يوفر هذا الدليل مسارًا قابلاً للتطبيق لـ Stencil ويوجه متاجر Catalyst إلى محوّل إطار عمل.

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

اختر مسار متجر#

  • Stencil: ثبّت المحمّل باستخدام Script Manager أو Scripts API، ثم أضف الحاوية في قالب مخصص.
  • Catalyst: أضف النص البرمجي والمكون في تطبيق Catalyst React/Next.js؛ اتبع React / Next.js.
  • Blueprint القديم: انتقل إلى متجر مدعوم أو اطلب من مطور BigCommerce تحديد نقطة إدراج آمنة. يعامل توثيق Scripts API الحالي Blueprint بشكل منفصل.

تحتاج إلى صلاحية تعديل القالب، وقالب أو قناة في بيئة ما قبل الإنتاج، وShop ID وPublishable Key من ideal.house، وSKU واحد على الأقل من BigCommerce مستورد في 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 فقط من المثال مع بيانات الاعتماد الآمنة للمتصفح. تُعد Script Manager الواجهة المقابلة في لوحة التحكم لـ 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 تغييرات خيارات المنتج عبر الشيفرة الخاصة بتفاصيل المنتجات في القالب. أضف محوّلًا خاصًا بالعميل عند النقطة التي يحدد فيها القالب الحالي الاستجابة النهائية لمتغير المنتج:

js
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 تخصيص تنفيذ تفاصيل المنتج الافتراضي أو استبداله، لذا لا يفترض هذا الدليل وجود حدث موحد لتغيير الخيارات. احذف الحاوية القديمة قبل إدراج الجديدة.

المشهد السريع والصفحات الديناميكية#

قد يؤدي العرض السريع والبحث متعدد المرشحات وتقسيم النتائج إلى صفحات والتنقل من جهة العميل إلى استبدال DOM المنتج. أضف حاوية نظيفة في كل قالب معروض، واستدعِ دالة الربط نفسها بعد دالة رد النداء الموثقة للعرض في القالب. لا تستنسخ حاوية سبق أن ملأها SDK.

يستخدم Catalyst عرض React من جهة العميل، ولا يتوفر فيه سياق Stencil Handlebars. حمّل SDK مرة واحدة في الهيكل الرئيسي للتطبيق، وحدد مفتاح مكوّن العرض باستخدام SKU لمتغير المنتج المحدد كما في دليل React/Next.js.

استيراد وتعيين بيانات المنتج#

عيّن قيم BigCommerce sku إلى ideal.house sku؛ بالنسبة للأنواع، استخدم كل SKU نوع بدلاً من معرف المنتج الأصلي. بيانات الكتالوج لـ BigCommerce لا تتم مزامنتها بواسطة SDK المتصفح.

استخدم تحميل المنتجات للعقد المستورد المعتمد، ثم تحقق من استيراد المنتجات، وحالة المهمة، وقائمة المنتجات، وتحديث المنتجات، وحذف المنتج، والأخطاء والمحاولات. أي تصدير لـ BigCommerce API أو ويب هوك أو مزامنة مجدولة هو مكيّف يعمل على مستوى العميل.

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

قبل الإطلاق، اختبر منتجًا بسيطًا وكل تركيبة خيارات ومنتجًا بلا SKU ورمز SKU غير موجود في ideal.house. افحص صفحة المنتج وبطاقات الفئات والعرض السريع والتنقل متعدد المرشحات وزري الرجوع والتقدم في المتصفح وتخطيط الهاتف المحمول وسلوك الموافقة وكل قناة متجر نشطة. تحقق في DevTools من نجاح طلب SDK واحد ومن التطابق الدقيق بين رمز المنتج وSKU.

لإزالة التكامل، احذف إدخال Script Manager أو سجل Scripts API، وأزل جميع وسوم الحاويات وشيفرة المحوّل من القالب. انشر القالب بعد التنظيف، ثم امسح ذاكرة التخزين المؤقت لواجهة المتجر وCDN. تحقق من غياب طلب SDK عن جميع القنوات.

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