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

تكامل WooCommerce#

أضف أزرار Room Visualizer إلى صفحات منتجات WooCommerce واحتفظ برمز منتج ideal.house متزامناً مع SKU متغير المنتج المحدد.

حالة المراجعة: تمت مراجعة وثائق وسلوك WooCommerce العام في 7 سبتمبر 2026. لم يتم اعتماد هذا التنفيذ في متجر عميل. يمكن للقوالب الكلاسيكية، وقوالب البلوكات، وملحقات التباين، وإضافات العرض السريع أن تعرض DOM مختلفة؛ اختبر الكومة الفعلية على النسخة التجريبية.

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

النطاق والشروط المسبقة#

يستهدف هذا الدليل WooCommerce على WordPress. يستخدم ملحق موقع مخصص صغير أو قالب فرعي، ومحمّل أصول WordPress القياسي، وخطافات منتجات WooCommerce. إنه ليس ملحق WordPress ideal.house قابل للتثبيت.

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

حد أدنى من علامات SDK#

هذا هو عقد 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 للكتالوج المستورد. لا تضع معرفات قاعدة بيانات WooCommerce في data-product-code إلا إذا استخدمت هذه المعرفات عمدًا كـ SKUs للكتالوج.

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

أضف هذه الشيفرة إلى ملف functions.php في قالب فرعي أو إلى إضافة خاصة بالموقع. استبدل القيم النائبة.

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') return $tag;

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

إذا كنت تدعم إصدارات WooCommerce على WordPress قبل 6.3، مرر true كآخر وسيط enqueue وأضف async في المصفي.

عرض مضيف صفحة المنتج#

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

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

أكد وجود الخطاف في قالب منتجك. قد يتطلب قالب يستبدل قالب WooCommerce أو كتلة مجموعة المنتجات تكامل بلوك أو خطاف WooCommerce آخر موثق.

مزامنة متغير المنتج المحدد#

يُطلق نموذج المتغيرات المضمّن في WooCommerce أحداث دورة حياة المتغيرات عبر jQuery. أضف ملفًا محليًا، مثل assets/js/idealhouse-woocommerce.js، وسجّله للتحميل مع الاعتماديتين jquery وwc-add-to-cart-variation، ثم استخدم:

js
(function ($) {
  function render(host, sku) {
    host.replaceChildren();
    const code = typeof sku === 'string' ? sku.trim() : '';
    if (!code) return;

    const container = document.createElement('div');
    container.dataset.idealhouseButtonContainer = '';
    container.dataset.productCode = code;
    host.append(container);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

هذا الملف هو محوّل WooCommerce خاص بالعميل. إذا استبدل ملحق الاختلافات البرنامج النصي للنموذج القياسي، فاستخدم دالة استدعاء الاختيار المُوثَّقة في ذلك الملحق بدلاً من افتراض استمرار تشغيل هذه الأحداث. لا تقم بتحديث سمة واحدة فقط لعنصر تم معالجته مسبقاً بواسطة SDK؛ استبدله بعنصر نظيف.

شبكات المنتجات، العرض السريع، والتنقل AJAX#

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

يمكن لملحقات العرض السريع وكتل WooCommerce حقن المنتجات بعد التحميل الأولي للصفحة. ضع العنصر الاستضافي في قالب العرض الخاص بهم وقم بتشغيل جسر render() الخاص بك من دالة إكمال مُوثَّقة في تلك الأداة. إذا لم يتوفر استدعاء ثابت، فقد يكتشف MutationObserver نطاقياً عقد .idealhouse-host جديدة، لكن العميل يتحمل أداءه ودورة حياته.

تعيين الكتالوج والاستيراد#

اربط قيمة WC_Product::get_sku() وقيمة WC_Product_Variation::get_sku() لكل متغير بحقل sku في ideal.house. يجب ألا يشترك المنتج الأصل والمنتج الفرعي في الرمز نفسه إذا كانا يمثلان موارد مرئية مختلفة.

لا يدفع WooCommerce تغييرات الكتالوج تلقائياً إلى ideal.house. استخدم رفع المنتج وإرشاداته لـ الاستيراد، حالة المهام، العرض، التحديثات، الحذف، ومعالجة إعادة المحاولة. أي جسر تصدير مجدول أو webhook يقع ضمن تنفيذ العميل.

التحقق قبل الإطلاق#

  1. اختبر منتجًا بسيطًا، ومنتجًا ذا متغيرات، ومنتجًا بلا SKU، ومنتجًا له SKU غير موجود في ideal.house.
  2. تأكد من طلب SDK مرة واحدة وأن علامة السكربت تحتفظ بكلتا سماتي الاعتماد.
  3. اختر كل متغير وتحقق من أن data-product-code يساوي SKU الخاص به.
  4. إعادة تعيين نموذج التباين؛ يجب أن تختفي الحاوية القديمة.
  5. اختبر شبكة منتجات، وعرض سريع، وفلاتر AJAX، وقطع عربة التسوق، وزر الإضافة إلى العربة الثابت على المحمول، وزر رجوع/تقدم في المتصفح حيث ينطبق.
  6. اختبر أثناء تسجيل الخروج، مع تفعيل ضوابط الموافقة والتخزين المؤقت للإنتاج.
  7. تحقق من عدم ظهور Client Secret في HTML، JavaScript، السجلات، أو خرائط المصادر.

إزالة التكامل#

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

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