تكامل Vue / Nuxt#

استخدم SDK الخاص بمتصفح ideal.house مباشرةً في Vue أو Nuxt، وأبقِ حاوية الزر الذي ينشئه متزامنة مع حالة المنتج التفاعلية. لا يتضمن هذا الدليل حزمة npm لـ ideal.house مخصصة لـ Vue.

حالة التحقق: تم فحص العلامة SDK مقابل قالب Dashboard الحالي؛ تمت مراجعة التوثيق الرسمي لـ Vue وNuxt في 7 سبتمبر 2026. لم يتوفر تطبيق عميل أو بيانات اعتماد إنتاج.

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

المتطلبات السابقة والحدود#

جهّز Shop ID وPublishable Key وقيمة SKU مستوردة وسجلًا تفاعليًا لمتغير المنتج المحدد. يمكن أن يظهر Shop ID وPublishable Key على جانب العميل. احتفظ بـ Client Secrets ومفاتيح AI API وبيانات اعتماد استيراد المنتجات على الخادم.

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

يجب أن تطابق قيمة Product Code تمامًا لـ sku الكتالوج.

مكوّن Vue#

امنح الحاوية key حتى ينشئ Vue عقدة نظيفة عند تغيير SKU المختار:

vue

<script setup lang="ts">
import { computed } from 'vue'

const props = defineProps<{ productCode?: string | null }>()
const code = computed(() => props.productCode?.trim() || '')
</script>

<template>
  <div
    v-if="code"
    :key="code"
    data-idealhouse-button-container
    :data-product-code="code"
  />
</template>

مرّر SKU الأساسي لمتغير المنتج المحدد. لا تعرض شيئًا إذا لم يكتمل الاختيار، بدلًا من إبقاء الرمز السابق ظاهرًا.

محمّل Nuxt#

يدعم Nuxt useHead وسوم النصوص الخارجية. تسجيله مرة واحدة في app.vue أو تخطيط يغطي صفحات المنتجات:

vue

<script setup lang="ts">
const config = useRuntimeConfig()

useHead({
  script: [
    {
      key: 'idealhouse-room-visualizer-sdk',
      src: 'https://sdk.ideal.house/sdk.js',
      async: true,
      'data-shop-id': config.public.idealhouseShopId,
      'data-publishable-key': config.public.idealhousePublishableKey,
    },
  ],
})
</script>

ضع قيمًا علنية فقط تحت runtimeConfig.public. لـ Vue العادي، أضف النص مرة واحدة إلى قشرة التطبيق HTML أو أنشئه في onMounted() للمكون الجذري مع فحص تكرار querySelector. يجب أن تعمل واجهات DOM على العميل.

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

اربط selectedVariant.sku بالمكوّن. تتعامل العقدة ذات المفتاح مع تغييرات الخيارات دون استخدام دالة غير موثقة في SDK. عندما تتغير بيانات المسار في Nuxt مع إعادة استخدام مثيل المكوّن، يُحدَّث الرمز المحسوب وتُزال الحاوية القديمة.

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

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

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

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

يبقى عميل نظام التجارة الإلكترونية على الخادم، وإشعارات الويب، والمزامنة المجدولة، وبيانات الاعتماد الخاصة، خارج SDK الخاص بالمتصفح.

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

اختبر SSR وربط HTML بالمنطق التفاعلي في المتصفح، وإعادة التحميل الكامل، والتنقل على جانب العميل، وزري الرجوع والتقدم في المتصفح، وكل متغير منتج، وقيم SKUs الفارغة أو غير المعروفة، والبطاقات المكررة، والعرض السريع، و<KeepAlive>، وحالات التحميل، والهاتف المحمول، والموافقة، وبناء نسخة الإنتاج. تأكد من إرسال طلب SDK واحد بالضبط ومن التطابق التام بين Product Code في DOM وSKU. افحص الموارد المبنية للتأكد من خلوها من الأسرار.

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