React / Next.js इंटीग्रेशन#

ideal.house ब्राउज़र SDK का उपयोग सीधे React या Next.js में करें। इस गाइड में कोई अलग ideal.house React npm पैकेज नहीं है।

** सत्यापन स्थिति:** SDK मार्कअप को वर्तमान डैशबोर्ड टेम्पलेट के विरुद्ध जाँचा गया था; React और Next.js आधिकारिक जीवनचक्र/स्क्रिप्ट दस्तावेज़ीकरण 7 सितंबर 2026 को समीक्षा किया गया था। कोई ग्राहक एप्लिकेशन या प्रोडक्शन क्रेडेंशियल्स उपलब्ध नहीं थे, इसलिए बनी हुई एप्लिकेशन को सिर से पूंछ तक सत्यापित करें।

** SDK को लोड करने से पहले:** डैशबोर्ड → सेटिंग्स खोलें, अपने स्टोरफ्रंट ओरिजिन को Allowed Origins (CORS) में जोड़ें, और सहेजें पर क्लिक करें। प्रकाशित होस्टनेम और किसी भी प्रीव्यू या स्टेजिंग ओरिजिन को शामिल करें जिन्हें आप उपयोग करते हैं; कई ओरिजिन को कॉमा से अलग करें। कॉन्फ़िगरेशन के चरण देखें।

पूर्वशर्तें और सीमाएँ#

Shop ID, Publishable Key, एक आयातित कैटलॉग SKU, और एक क्लाइंट-रेंडर्ड उत्पाद/वैरिएशन मान तैयार करें। Publishable Key ब्राउज़र मार्कअप में मौजूद हो सकता है। Client Secrets, AI API कीज़, और कोई भी निजी उत्पाद-आयात क्रेडेंशियल्स को सर्वर पर रखें।

SDK DOM कंटेनर खोजता है। React तय करता है कि वे नोड कब माउंट किए जाते हैं; आपका इंटीग्रेशन वर्तमान वैरिएशन को हल करने और उसके SKU बदलने पर कंटेनर को बदलने के लिए ज़िम्मेदार है।

न्यूनतम 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>

data-product-code का ideal.house कैटलॉग sku से पूर्णतः बराबर होना चाहिए।

React कंपोनेंट#

जब भी उत्पाद कोड बदलता है, एक नया कंटेनर माउंट करें। key React को DOM नोड को बदलने के लिए बाध्य करता है, बजाय उस कंटेनर को फिर से उपयोग करने के जिसे SDK ने पहले से भर दिया हो सकता है:

tsx

type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

चयनित वेरिएंट SKU पास करें, न कि प्रोडक्ट शीर्षक, रूट स्लग, डेटाबेस आईडी, या विकल्प लेबल। यदि चयन अधूरा है, तो null रेंडर करें।

Next.js App Router लोडर#

SDK को उत्पाद पेजों को कवर करने वाले सबसे संकीर्ण साझा लेआउट में एक बार रखें। Next.js कुछ हाइड्रेशन के बाद लोड होने वाली स्क्रिप्ट के लिए afterInteractive का दस्तावेज़ीकरण करता है:

tsx

import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

एक लेआउट से IdealhouseSdk एक बार रेंडर करें, फिर वैरिएंट चयन के मालिक एक क्लाइंट कंपोनेंट के अंदर RoomVisualizerButton रेंडर करें। NEXT_PUBLIC_ से प्रीफिक्स वाले मान ब्राउज़र तक भेजे जाते हैं; इन्हें केवल Shop ID और Publishable Key के लिए उपयोग करें।

Pages Router या सादा React के लिए, स्क्रिप्ट को HTML शेल में एक बार बनाएं, या एक एकल टॉप-लेवल इफ़ेक्ट का उपयोग करें:

tsx

useEffect(() => {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;
  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);
}, []);

React Strict Mode विकास के दौरान जानबूझकर एक अतिरिक्त सेटअप चक्र चलाता है, इसलिए डुप्लिकेट की जाँच आवश्यक है। किसी एक उत्पाद कंपोनेंट के अनमाउंट होने पर साझा SDK टैग न हटाएँ।

नेविगेशन, सूचियाँ, और वैरिएंट#

क्लाइंट-साइड रूट परिवर्तन लेआउट स्क्रिप्ट को फिर से लोड नहीं करते। यदि एक ही SKU कई एक साथ माउंट किए गए व्यूज़ में दिखाई दे सकता है, तो प्रत्येक उत्पाद नियंत्रण को स्थिर रूट पहचान और SKU से की करें। ग्रिड के लिए, हर कार्ड को अपना अपना SKU चाहिए। जब अनंत स्क्रॉल कार्ड जोड़ता है, React स्वाभाविक रूप से नए साफ़ कंटेनर माउंट करता है।

वैरिएंट चयन के लिए, अपने कॉमर्स स्टेट से selectedVariant.sku व्युत्पन्न करें और इसे productCode के रूप में पास करें। किसी अदस्तावेज़ीकृत SDK रिफ्रेश विधि को कॉल न करें। क्विक-व्यू ड्रॉअर्स और रूट संक्रमण को अपने पिछले कंपोनेंट को अनमाउंट करना चाहिए ताकि प्रोसेस किया गया DOM अगले उत्पाद में रिस न हो।

यदि React हाइड्रेशन एक असंगति की रिपोर्ट करता है, तो सुनिश्चित करें कि सर्वर और पहला क्लाइंट रेंडर सहमत हों। क्लाइंट कॉमर्स स्टेट SKU को हल कर लेने तक कोई कंटेनर रेंडर न करना वैध है।

उत्पाद डेटा इम्पोर्ट करें#

कॉमर्स बैकएंड के कैनोनिकल वैरिएनट SKU को ideal.house sku से मैप करें। उत्पाद अपलोड का उपयोग करें, फिर उत्पाद आयात करें, कार्य की स्थिति, उत्पादों की सूची देखें, उत्पाद अपडेट करें, उत्पाद हटाएँ, और त्रुटियाँ और पुनः प्रयास देखें।

कोई भी बैकएंड कैटलॉग क्वेरी, वेबहुक, नियोजित सिंक, या लॉन्च-टोकन सेवा एप्लिकेशन कोड बना रहती है; ब्राउज़र SDK इसे प्रदान नहीं करता।

सत्यापित करें और हटाएं#

सर्वर रेंडर/हाइड्रेशन, हार्ड लोड, क्लाइंट नेविगेशन, ब्राउज़र बैक/फॉरवर्ड, वैरिएंट परिवर्तन, null/अज्ञात SKUs, दोहराए गए कार्ड, क्विक व्यू, Suspense/लोडिंग स्थितियों, मोबाइल, सहमति नियंत्रण, और प्रोडक्शन बिल्ड का परीक्षण करें। एक SDK अनुरोध और सटीक DOM उत्पाद कोड/SKU समता की पुष्टि करें। गलती से रह गए सीक्रेट्स के लिए बिल्ड किए गए क्लाइंट बंडल की जांच करें।

हटाने के लिए, साझा SDK कंपोनेंट/टैग और सभी RoomVisualizerButton उपयोगों को हटाएं, दो सार्वजनिक पर्यावरण चर हटाएं, फिर से बिल्ड करें, और पुष्टि करें कि कोई SDK URL या data-idealhouse-* मार्कअप शेष नहीं है।