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

تكامل Shopware 6#

أضف Room Visualizer من خلال إضافة Shopware 6 أو قالب مخصص، واستخدم رقم المنتج المحدد في قناة المبيعات بوصفه Product Code في ideal.house.

حالة التحقق: روجعت وثائق واجهة متجر Shopware في 7 سبتمبر 2026. لم يتوفر متجر عميل للاختبار. يستهدف هذا المسار واجهة متجر Twig القياسية في Shopware 6؛ وتحتاج واجهات المتاجر ذات الواجهة المنفصلة أو القائمة على مكونات قابلة للتركيب إلى محوّل خاص بإطار العمل المستخدم.

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

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

جهّز متجر تطوير، وصلاحية الوصول إلى الشيفرة المصدرية للإضافة أو القالب، وقناة مبيعات في بيئة ما قبل الإنتاج، وShop ID، وPublishable Key، وأرقام المنتجات المستوردة. اعمل ضمن إضافة أو قالب فرعي بدلًا من تعديل نواة Storefront أو قالب مورّد.

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

ربط Shopware productNumber بدقة إلى ideal.house sku. SDK لا يبحث في واجهة Store API الخاصة بـ Shopware.

تمديد قالب المنتج#

في إضافتك، قم بتمديد قالب Twig/الكتلة المستخدمة بالقرب من أداة الشراء في إصدار Shopware المثبت. اعرض عنصرًا حاويًا باستخدام منتج قناة المبيعات الحالي:

twig
{% sw_extends '@Storefront/storefront/component/buy-widget/buy-widget-form.html.twig' %}

{% block buy_widget_buy_container %}
    {{ parent() }}
    {% if page.product.productNumber %}
        <div class="idealhouse-host">
            <div
                data-idealhouse-button-container
                data-product-code="{{ page.product.productNumber|escape }}">
            </div>
        </div>
    {% endif %}
{% endblock %}

يمكن أن تتغير أسماء الكتلة والسياق بين إصدارات Shopware والسمات. فحص قالب الإصدار النشط، اختر أضيق كتلة تمديد، وتأكد من توفر page.product هناك. بالنسبة لبطاقة منتج، استخدم سياق المنتج الخاص بالبطاقة بدلاً من ذلك.

تحميل SDK#

يمكن لإضافات Shopware إضافة JavaScript لواجهة المتجر وتجاوز القوالب. أضف نقطة دخول محلية لواجهة المتجر تنشئ سكربت SDK مرة واحدة:

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

ابنِ موارد واجهة المتجر وفعّل الإضافة أو القالب باتباع الإجراء الخاص بإصدار Shopware لديك. استخدم قيم إعدادات لبيانات الاعتماد في الإضافات القابلة لإعادة الاستخدام؛ ولا تُضمّن في المحتوى المعروض سوى Publishable Key الآمن للاستخدام في المتصفح.

المتغيرات والمحتوى الديناميكي#

غالبًا ما يمثّل Shopware متغيرات المنتجات القابلة للشراء بوصفها منتجات منفصلة، لكل منها productNumber وURL أساسي خاص بها. عند الانتقال مع تحميل الصفحة كاملةً، يُنتج Twig المعروض على الخادم الرمز الجديد تلقائيًا. إذا كان قالبك يبدّل متغيرات المنتجات دون تحميل الصفحة، فاربط دالة رد النداء الموثقة عند اكتمال التبديل بما يلي:

js
function replaceIdealhouseProduct(host, productNumber) {
  host.replaceChildren();
  const code = String(productNumber || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

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

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

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

أي مزامنة عبر Store API/Admin API، أو مهمة مجدولة، أو تكامل مع Flow Builder أو إشعارات الويب، تتطلب شيفرة منفصلة ينفّذها العميل.

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

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

للإزالة، عطّل/ألغِ تثبيت الإضافة أو أزل Twig السمة الفرعية و JavaScript، أعد بناء موارد واجهة المتجر، امسح التخزين المؤقت، وتأكد من عدم بقاء أي طلب SDK أو حاوية.

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