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

تكامل SHOPLINE#

دمج Room Visualizer مع متجر SHOPLINE عبر الإنترنت من خلال توسعة تطبيق السمة أو كتلة مخصصة ذات تحكم في السمة.

حالة التحقق: تمت مراجعة وثائق متجر SHOPLINE عبر الإنترنت لإصدار 2.x/3.0 من السمة في تاريخ 7 سبتمبر 2026. لم يكن هناك تطبيق شريك أو متجر اختبار للتاجر متاحًا. تختلف صيغة القوالب وأنواع التوسعات المدعومة حسب جيل متجر الإنترنت، لذا تحقق مقابل إصدار المتجر الدقيق.

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

اختر سطح التكامل#

  • للحصول على تطبيق عام قابل لإعادة الاستخدام على Online Store 2.0/2.1، تُوصي SHOPLINE باستخدام Theme App Extension مع App Block وApp Embed Block اختياري.
  • توفر قوالب Online Store 3.0 كتلًا قابلة لإعادة الاستخدام مع موارد JavaScript اختيارية وApp Blocks.
  • واجهات برمجة تطبيقات Script Tag/Asset APIs قديمة أو تعتمد على الإصدار/نوع التطبيق؛ لا تخترها دون التحقق من جدول التوافق الخاص بـ SHOPLINE.
  • لتخصيص السمة لمتجر واحد، استخدم بنية الكتلة/القالب والأصول الخاصة بالإصدار النشط.

حضّر متجر تطوير، وصولًا إلى توسعة/سمة، Shop ID، Publishable Key، وأكواد المتغيرات المستوردة.

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

يجب أن يتطابق رمز المنتج مع ideal.house sku في الكتالوج. لا تدعي هذه الوثائق وجود تطبيق ideal.house لـ SHOPLINE قابل للتثبيت.

ابنِ كتلة السمة#

أنشئ كتلة تطبيق أو كتلة سمة عامة تعرض حاوية على صفحات تفاصيل المنتج. استخدم كائن المنتج/المتغير الدقيق ودوال تهريب الأحرف المساعدة الموثّقة لجيل متجر الإنترنت الخاص بك. يجب أن يكون واجهة متجر HTML النهائية على النحو التالي:

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

في مصدر القالب، استبدل CHAIR-OAK-01 بتعبير SKU/الرمز للمتغير المحدد الحالي. لا تلصق تعبير Shopify Liquid داخل قوالب Handlebars SHOPLINE 3.0؛ فهذه لغات وعقود كائنات مختلفة.

بالنسبة لكتلة التطبيق، أضفها إلى قسم المنتج في محرر السمة. بالنسبة للتكامل، استخدمه لتحميل SDK عالميًا بدون واجهة مستخدم مرئية. عادةً ما تتطلب كتل التطبيقات من التاجر تمكينها/وضعها بعد التثبيت.

تحميل SDK مرة واحدة#

في أصل JavaScript الخاص بالتوسعة/السمة، أنشئ السكربت بالإعدادين العامّين قبل إرفاقه:

js
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);
}

استخدم إعدادات التوسعة أو المعلمات الديناميكية لبيانات الاعتماد الخاصة بعدة تجار. لا تعرض سوى Publishable Key؛ واحتفظ بأسرار التطبيق على خادمك.

المتغيرات المحددة والأقسام الديناميكية#

اربط دالة رد النداء الموثقة لاختيار المنتج في القالب النشط بمحوّل ينفّذه العميل:

js
function setIdealhouseVariant(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);
}

يمكن تخصيص قوالب SHOPLINE، لذلك لا يفترض هذا الدليل وجود حدث موحّد لتغيير متغير المنتج في واجهة المتجر. توثّق Online Store 3.0 أحداث الأقسام والكتل في محرر القالب، لكنها أحداث دورة حياة المحرر، وليست أحداث اختيار المشتري لمتغير المنتج.

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

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

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

تُعد مزامنة SHOPLINE Admin API، وإشعارات الويب، وOAuth للتطبيق، وتوزيعه عبر متجر التطبيقات، أعمالًا ضمن المحوّل الذي ينفّذه العميل.

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

اختبر التثبيت وتمكين كتلة التاجر، منتجًا بسيطًا، كل متغير، الأكواد المفقودة/غير المعروفة، البطاقات، العرض السريع، الفلاتر، التنقل بأسلوب SPA، الهاتف المحمول، الموافقة، معاينة محرر السمة، وكل إصدار مدعوم من Online Store. أكد طلب SDK واحد وتطابق الرمز/SKU الدقيق.

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

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