تكامل Squarespace#

ثبّت Room Visualizer على Squarespace باستخدام Code Injection وضع حاويات خاصة بالمنتج حيث يسمح محرر الصفحة بالكود المخصص.

حالة التحقق: روجعت وثائق مركز مساعدة Squarespace في 7 سبتمبر 2026. لم يتوفر موقع Squarespace خاص بعميل للاختبار. يتطلب حقن الشيفرة وكتل الشيفرة التي تستخدم JavaScript خططًا مؤهلة، ولا يشمل دعم Squarespace الشيفرة المخصصة، وقد يؤثر تحميل Ajax فيها.

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

النطاق والمتطلبات المسبقة#

يناسب هذا المسار أكثر كتالوجًا صغيرًا بصفحات منتجات ثابتة، أو موقعًا تتحكم فيه بطبقة بيانات صريحة لرموز المنتجات. تحتاج إلى خطة مؤهلة، وصلاحية مالك الموقع، وShop ID، وPublishable Key، وقيم SKUs مستوردة في ideal.house.

لا يُوفّر Squarespace امتداد ideal.house في هذا الدليل. لا يضمن محرّر المنتجات القياسي لديه واجهة برمجة تطبيقات JavaScript API عامة ثابتة لـ 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>

يجب أن يطابق Product Code تمامًا sku الكتالوج المستورد. لا تستخدم Client Secret في Code Injection.

تثبيت المحمّل#

افتح الموقع الإلكتروني ← الصفحات ← الشيفرة المخصصة ← حقن الشيفرة (قد تختلف التسمية حسب إصدار الموقع). الصق <script> الخاص بـ SDK في التذييل، واستبدل القيمتين النائبتين، ثم احفظ. تعمل الشيفرة المحقونة في التذييل على صفحات الموقع قبل </body>؛ ولا تدعم صفحات إتمام الشراء الشيفرة المحقونة.

ثبّت المحمّل مرة واحدة فقط. إذا أضافه تكامل آخر بالفعل، فأزل النسخة المكررة.

وضع زر منتج#

حيثما يسمح محرر الصفحة بكتلة شيفرة تدعم JavaScript، ضع ما يلي:

html

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

استخدم SKU الخاص بذلك المنتج بعينه. في Squarespace 7.1، قد لا تقبل تخطيطات المتجر أو تفاصيل المنتج كتلًا عشوائية في منطقة معلومات المنتج الرئيسية. البديل العملي هو صفحة ذات تخطيط عادي تحتوي على كتلة منتج وكتلة شيفرة مجاورة، زوج واحد لكل منتج. تأكد من بقاء صفحة المتجر مفعّلة لأن كتل المنتجات تعتمد عليها.

للكتالوجات الأكبر، يمكن للمطوّر إدراج الحاويات بالاعتماد على جدول ربط ثابت يديره العميل، مثل ربط مسار URL بقيمة SKU:

const skuByPath = {
  '/shop/oak-chair': 'CHAIR-OAK-01',
  '/shop/walnut-chair': 'CHAIR-WALNUT-01'
};

function renderForPath() {
  const host = document.querySelector('[data-idealhouse-host]');
  const sku = skuByPath[location.pathname];
  if (!host) return;
  host.replaceChildren();
  if (!sku) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = sku;
  host.append(container);
}

يتولى العميل كتابة شيفرة ربط URL وإدراج العنصر الحاوي ودالة رد النداء الخاصة بالتنقل. لا تستخرج الحالة الداخلية الخاصة بـ Squarespace ولا تفترض أن بنيتها ثابتة.

متغيرات المنتجات والعرض السريع وتحميل Ajax#

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

قد يستبدل العرض السريع وكتل المنتجات وتحميل الصفحات عبر Ajax محتوى الصفحة. تحذّر Squarespace من أن تحميل Ajax قد يتعارض مع الشيفرة المخصصة. اختبر القالب المستخدم تحديدًا؛ وعند الضرورة عطّل تحميل Ajax أو استدعِ renderForPath() من آلية تنقل تديرها أنت. يُستخدم MutationObserver بوصفه حلًا أخيرًا ضمن محوّل ينفّذه العميل، ويجب حصر نطاقه في منطقة المنتج.

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

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

لا يزامن SDK الخاص بالمتصفح منتجات Squarespace. يتولى العميل أي تصدير عبر Commerce API أو إشعارات ويب أو مهام مجدولة.

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

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

لإزالة التكامل، احذف الشيفرة المحقونة في التذييل وجميع كتل الشيفرة والعناصر الحاوية وسكربتات الربط، ثم احفظ وامسح ذاكرة التخزين المؤقت. تحقق من عدم وجود طلب SDK أو عنصر data-idealhouse-* في الصفحة المنشورة.