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

تكامل React / Next.js#

استخدم SDK الخاص بمتصفح ideal.house مباشرةً في React أو Next.js. لا يتضمن هذا الدليل حزمة npm منفصلة لـ ideal.house مخصصة لـ React.

حالة المراجعة: تم التحقق من علامات SDK مقابل قالب Dashboard الحالي؛ وتم مراجعة توثيق دورة حياة/البرنامج النصي الرسمي من React وNext.js في 7 سبتمبر 2026. لم يتوفر تطبيق عميل أو بيانات اعتماد إنتاج، لذا تحقق من التطبيق المدمج نهايةً بنهاية.

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

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

جهّز Shop ID وPublishable Key وقيمة SKU مستوردة في الكتالوج وقيمة منتج أو متغير منتج معروضة على جانب العميل. يمكن أن يظهر Publishable Key في وسوم المتصفح. احتفظ بـ Client Secrets ومفاتيح AI API وأي بيانات اعتماد خاصة باستيراد المنتجات على الخادم.

يكتشف SDK حاويات DOM. يتحكم React في توقيت تركيب هذه العقد؛ ويتولى تكاملك تحديد متغير المنتج الحالي واستبدال الحاوية عند تغيّر SKU الخاص به.

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

يجب أن يعادل data-product-code تمامًا كتالوج ideal.house sku.

مكون React#

ثبّت حاوية جديدة كلما تغير رمز المنتج. يفرض key على React استبدال عقدة DOM بدلاً من إعادة استخدام حاوية قد يكون SDK قد ملأه بالفعل:

tsx
type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

مرر SKU لمتغير المنتج المحدد، وليس عنوان المنتج أو مسار التوجيه أو معرف قاعدة البيانات أو تسمية الخيار. إذا كان الاختيار غير مكتمل، فاعرض null.

محمّل App Router لـ Next.js#

ضع SDK مرة واحدة في أضيق تخطيط مشترك يغطي صفحات المنتجات. يوثّق Next.js استخدام afterInteractive للسكربتات التي تُحمّل بعد ربط جزء من HTML المعروض على الخادم بالمنطق التفاعلي في المتصفح:

tsx
import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

اعرض IdealhouseSdk مرة واحدة من تخطيط، ثم اعرض RoomVisualizerButton داخل مكون عميل يمتلك اختيار المتغير. القيم التي تسبق بـ NEXT_PUBLIC_ تُرسَل إلى المتصفح؛ استخدمها فقط لـ Shop ID وPublishable Key.

لمُوجّه Pages أو React الصافي، أنشئ البرنامج النصي مرة واحدة في غلاف HTML ، أو استخدم دالة تأثير واحدة في المستوى الأعلى:

tsx
useEffect(() => {
  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);
}, []);

يقوم React Strict Mode عمدًا بدورة إعداد تطوير إضافية، لذا يجب فحص التكرار. لا تزيل وسم SDK المشترك عندما يتم إزالة مكون منتج فردي.

التنقل والقوائم والمتغيرات#

لا تعيد تغييرات المسارات على جانب العميل تحميل سكربت التخطيط. امنح كل عنصر تحكم في المنتج مفتاحًا يجمع هوية مسار ثابتة مع SKU إذا كان SKU نفسه قد يظهر في عدة عروض مركّبة في الوقت نفسه. في الشبكات، تحتاج كل بطاقة إلى SKU خاص بها. عندما يضيف التمرير اللانهائي بطاقات، يركّب React تلقائيًا حاويات جديدة ونظيفة.

لالختيار المتغير، اشتق selectedVariant.sku من حالة تجارة الإلكترونية الخاصة بك ومررها كـ productCode. لا تستدعِ طريقة تحديث غير موثّقة لـ SDK. يجب أن تُزيل أدراج العرض السريع وتحولات التوجيه المكون السابق بحيث لا يتسرب DOM المعالج إلى المنتج التالي.

إذا أبلغ React عن عدم تطابق أثناء ربط HTML المعروض على الخادم بالمنطق التفاعلي، فتأكد من تطابق العرض على الخادم مع أول عرض على العميل. يجوز عدم عرض أي حاوية إلى أن تحدد حالة التجارة الإلكترونية على العميل قيمة SKU.

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

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

تبقى أي استعلامات لكتالوج الواجهة الخلفية، أو إشعارات ويب، أو مزامنة مجدولة، أو خدمة لرموز الإطلاق، ضمن شيفرة التطبيق؛ ولا يوفرها SDK الخاص بالمتصفح.

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

اختبر العرض على الخادم وربطه بالمنطق التفاعلي في المتصفح، والتحميل الكامل، والتنقل على جانب العميل، وزري الرجوع والتقدم في المتصفح، وتغييرات متغيرات المنتجات، وقيم SKUs الفارغة أو غير المعروفة، والبطاقات المكررة، والعرض السريع، وحالات Suspense والتحميل، والهاتف المحمول، وضوابط الموافقة، وبناء نسخة الإنتاج. تأكد من إرسال طلب SDK واحد ومن التطابق التام بين Product Code في DOM وSKU. افحص حزم العميل المبنية للتأكد من عدم تضمين أسرار فيها عن طريق الخطأ.

لإزالة التكامل، احذف مكوّن SDK أو وسمه المشترك وجميع استخدامات RoomVisualizerButton، وأزل متغيرَي البيئة العامّين، ثم أعد البناء وتحقق من عدم بقاء URL الخاص بـ SDK أو وسوم data-idealhouse-*.

المراجع الرسمية للإطار#