تكامل WordPress#

أضف ideal.house Room Visualizer إلى موقع WordPress عن طريق تحميل سكريبت مستعرض عام واحد وعرض حاوية يكون رمز المنتج فيها مطابقاً لـ SKU المستورد في الكتالوج.

حالة المراجعة: تمت مراجعة الوثائق في 7 سبتمبر 2026. لم يتم اعتماد هذا الدليل من البداية إلى النهاية مع قالب WordPress خاص بعميل. تحقق منه على نسخة تجريبية مطابقة لقالبك وإصدارات بناء الصفحات قبل النشر.

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

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

يغطي هذا الدليل مواقع محتوى WordPress، والقوالب الكلاسيكية، وقوالب البلوكات، ومبنيات الصفحات التي تتيح لك إضافة HTML. إذا كان الموقع يستخدم بيانات منتجات WooCommerce، فاستخدم دليل WooCommerce لاختيار المتغير.

الإعدادات:

• صلاحية المسؤول، وللتطبيق الدائم، قالب فرعي أو ملحق موقع مخصص صغير؛
• معرف المتجر Shop ID والمفتاح القابل للنشر Publishable Key من لوحة تحكم ideal.house；
• منتج واحد مستورد مسبقاً في ideal.house مع sku معروف；
• صفحة تجريبية يمكن تعطيل التخزين المؤقت/الضغط عليها أثناء الاختبار.

Publishable Key مخصص لوسوم المتصفح. لا تضع Client Secret أو مفتاح AI API مطلقًا في HTML الخاص بموقع WordPress.

تأكيد عقد SDK#

أصغر تثبيت مدعوم يتكون بالضبط من سكريبت SDK واحد والحاوية المولدة للزر:

<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>

يجب أن يتساوى data-product-code مع sku للكتالوج، بما في ذلك حالة الأحرف والترقيم. يمتلك SDK محتويات الحاوية. لا يوفر WordPress ملحق ideal.house في هذا الدليل.

تثبيت السكريبت على الموقع بالكامل#

توصي WordPress بتحميل سكريبتات الواجهة الأمامية عبر wp_enqueue_script(). أضف التالي إلى functions.php قالب فرعي أو ملحق موقع مخصص. يضيف المصفي السمتين البيانتيتين المطلوبتين للعلامة التي ينتجها WordPress.

add_action('wp_enqueue_scripts', function () {
    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);

استبدل القيمتين النائبتين. لا تقبل إصدارات WordPress قبل 6.3 الصيغة المصفوفية للوسيط النهائي wp_enqueue_script()؛ مرر true بدلاً من ذلك واستخدم مصفي script_loader_tag لإضافة async أيضاً.

لا تقم بتثبيت SDK مرة أخرى في كتلة رمز أو مدير علامات. في DevTools، يجب أن يعيد document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length 1.

وضع زر#

في محرر البلوكات، أضف كتلة Custom HTML حيث يجب أن يظهر الزر:

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

للبطاقات المتكررة، اعرض الوسوم نفسها من قالب الموقع، وطبّق على الرمز تهريب الأحرف المناسب لاستخدامه داخل سمة HTML:

<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

يجب أن يوفر قالبك أو ملحقك $idealhouse_product_code. لا تستخدم معرف منشور أو slug أو عنوان إلا إذا كانت هذه القيمة المطابقة هي أيضاً ideal.house sku المستورد.

تعيين المنتج والمتغير#

أنشئ جدول تعيين صريح قبل الإطلاق:

إذا تغيرت الصفحة بين المتغيرات، يجب على مُكيف العميل تعيين data-product-code الجديد. أزل الحاوية القديمة قبل إدراج الجديدة حتى لا يُعاد استخدام حالة العارض القديمة:

function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

هذا كود مكيّف العميل. لا يستدعي طريقة ideal.house غير موثقة ولا يخترع حدث WordPress؛ استدعه من رد الاتصال الموثق الذي يوفره قالبك أو أداة إنشاء الصفحات.

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

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

بعد تعديل القالب، امسح ذاكرة التخزين المؤقت في WordPress وCDN وإضافات التحسين. استثنِ https://sdk.ideal.house/sdk.js من إعادة كتابة إعدادات تأخير التحميل أو إرجائه إذا كانت إضافة الأداء تزيل سمات البيانات أو تؤخر السكربت إلى ما بعد تفاعل المستخدم.

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

محتوى WordPress لا يتم مزامنته تلقائياً. قم بتصدير الحقل المخصص المختار كـ sku واستورد السجلات المطابقة عبر رفع المنتجات. تابع مع استيراد المنتجات، وحالة المهمة، وقائمة المنتجات، وتحديث المنتجات، وحذف المنتج، والأخطاء وإعادة المحاولة.

التحقق قبل النشر#

1. افتح النسخة التجريبية في نافذة متصفح خاصة، وليس في معاينة محرر WordPress.
2. أكد أن طلب SDK يعود بنجاح ولمرة واحدة فقط.
3. فحص الحاوية وقارن data-product-code حرفياً بحرف مع sku المستورد.
4. أكد أن SKU مستورد ينتج تحكماً قابلاً للاستخدام في العارض، وأن SKU غير معروف لا يعرض تحكماً معطلاً.
5. اختبر تنقل أداة إنشاء الصفحات، والفلاتر، وزر رجوع/تقدم في المتصفح، والتخطيط على المحمول، وإعدادات الموافقة.
6. حدد كل متغير مدعوم وأكد أن الحاوية تُعاد إنشاؤها مع SKU الخاص بها.
7. فحص وحدة تحكم المتصفح واختبر مع تفعيل التخزين المؤقت/الضغط مرة أخرى.

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

أزل دالة تسجيل تحميل السكربت ومرشح script_loader_tag، ثم احذف كل كتلة data-idealhouse-button-container أو جزء قالب مقابل. امسح جميع ذاكرات التخزين المؤقت وتحقق من غياب URL الخاص بـ SDK من مصدر الصفحة ولوحة الشبكة.

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

• WordPress دليل القوالب: تضمين الأصول
• WordPress مرجع wp_enqueue_script()
• WordPress القوالب الفرعية