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

تكامل Adobe Commerce / Magento Open Source#

ثبّت Room Visualizer عبر وحدة Magento أو قالب مخصص، واربط SKU الخاص بالمنتج البسيط المعروض بالمنتج المقابل في كتالوج ideal.house.

حالة التحقق: تمت مراجعة وثائق الواجهة الأمامية لـ Adobe Commerce في 7 سبتمبر 2026. لم تتوفر بيئة مثبتة لدى تاجر. تستخدم قوالب Luma/Blank وHyvä وPWA Studio تقنيات JavaScript مختلفة؛ ويستهدف المثال العملي أدناه واجهة المتجر القياسية التي تستخدم RequireJS.

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

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

جهّز بيئة تطوير ووحدة مخصصة أو قالبًا فرعيًا وصلاحية النشر وShop ID وPublishable Key ورموز SKUs اختبارية مستوردة. لا تعدّل مطلقًا الملفات داخل vendor/ أو القالب الأساسي. يحتاج Hyvä وPWA Studio إلى محوّل Alpine/React خاص بهما، ولا يجوز نسخ شيفرة RequireJS دون مراعاة اختلافهما.

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

رمز المنتج هو قيمة sku المستوردة حرفيًا، وليس معرّف الكيان الرقمي في Magento.

أضف كتلة صفحة منتج#

أنشئ وحدة صغيرة أو تحديثًا لتخطيط القالب من أجل catalog_product_view. وجّه كتلة إلى قالب .phtml موضوع قرب إجراءات المنتج. يستطيع هذا القالب عرض SKU الأولي للمنتج بأمان:

php
<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

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

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

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

js
define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    var 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.appendChild(script);
  };
});

هيّئه بصورة تصريحـية من القالب، باتباع آلية text/x-magento-init التي توصي بها Adobe:

html
<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

ينتج هذا نفس عنصر SDK الخاص بعقد الحد الأدنى دون وضع بيانات الاعتماد في RequireJS URL. استخدم فقط Publishable Key في كود المتجر.

SKU قابل للتكوين مختار#

يعرض مكوّن المنتج القياسي القابل للتكوين حالة الاختيار عبر مكوّن Magento نفسه، لكن تخصيصات القوالب قد تغيّر بنيته. نفّذ امتدادًا من نوع mixin لـ RequireJS أو مستمعًا داخل وحدتك عند النقطة التي يحدد فيها القالب معرّف المنتج البسيط. اربط هذا المعرّف بـ SKU المقابل من بيانات JSON التي يقدمها الخادم، ثم استبدل العنصر الحاوي:

js
function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

  var container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = sku.trim();
  host.appendChild(container);
}

هذه الـ mixin وبيانات ID-to-SKU هي عمل محوّل العميل. لا تستدل على SKU الفرعي من تسميات الخيارات، ولا توثّق حدث ideal.house أو أسلوبًا غير جزء من عقد SDK العام.

المحتوى الديناميكي وذاكرة التخزين المؤقت#

أعد إنشاء الحاوية بعد تغيير عينات الألوان أو تحميل توصيات عبر AJAX أو فتح عرض سريع أو استبدال العنصر الحاوي بمحتوى خاص بالعميل. يُهيّئ حدث contentUpdated في Magento مكونات Magento داخل المحتوى المُدرج؛ لكنه لا يوفر SKU المحدد بمفرده، ولذلك يجب أن يحدد محوّلك الرمز الصحيح ويعرضه.

بعد تعديل الشيفرة، نفّذ خطوات النشر الملائمة للبيئة، وامسح ذاكرة التخزين المؤقت للتخطيطات والصفحات الكاملة والكتل، وأعد نشر المحتوى الثابت. اختبر مع تفعيل تجميع ملفات الإنتاج وتصغيرها وVarnish/CDN.

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

قم بربط رموز SKUs للمنتجات البسيطة والمنتجات الفرعية مع ideal.house sku. استخدم تحميل المنتجات، بما في ذلك الاستيراد، وحالة المهمة، والقائمة، والتحديثات، والحذف، ودليل إعادة المحاولة. تصديرات Magento، واستدعاءات Admin API، ومهام cron، وويب هوكات هي مكيفات من قبل العميل.

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

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

لإزالة التكامل، عطّل الوحدة المخصصة أو أزل تثبيتها، أو احذف ملفات التخطيط والقالب وRequireJS الخاصة بالقالب الفرعي. أعد نشر المحتوى الثابت، وامسح ذاكرة التخزين المؤقت، وتحقق من اختفاء URL الخاص بـ SDK والحاويات.

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