React / Next.js entegrasyonu#

ideal.house tarayıcı SDK'ünü doğrudan React veya Next.js içinde kullanın. Bu kılavuzda ayrı bir ideal.house React npm paketi yoktur.

Doğrulama durumu: SDK işaretleme, güncel Panel şablonuna karşı kontrol edildi; React ve Next.js resmi yaşam döngüsü/betiği dokümantasyonu 7 Eylül 2026 tarihinde incelendi. Müşteri uygulaması veya üretim kimlik bilgileri kullanılamadığından, derlenen uygulamayı uçtan uca doğrulayın.

SDK yüklenmeden önce: Panel → Ayarlar sayfasını açın, mağaza vitrini kökeninizi Allowed Origins (CORS) listesine ekleyin ve Kaydet düğmesine tıklayın. Yayımlanan ana bilgisayar adını ve kullandığınız önizleme veya test ortamı kökenlerini dahil edin; birden fazla kökeni virgülle ayırın. yapılandırma adımları bölümüne bakın.

Ön koşullar ve sınırlar#

Shop ID, Publishable Key, içe aktarılmış kataloğ SKU'ünü ve istemci tarafında görüntülenen bir ürün/çeşitlilik değerini hazırlayın. Publishable Key tarayıcı işaretlemede bulunabilir. Client Secrets, AI API anahtarlarını ve herhangi bir özel ürün içe aktarma kimlik bilgilerini sunucuda tutun.

SDK, DOM konteynerlerini keşfeder. React, bu düğümlerin ne zaman bağlandığının sahibidir; entegrasyonunuz, mevcut çeşitliliği çözmek ve SKU değiştiğinde konteyneri değiştirmenin sahibidir.

Minimal SDK sözleşmesi#

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 kataloğ sku'üne tam olarak eşit olmalıdır.

React bileşeni#

Ürün kodu her değiştiğinde taze bir konteyner bağlayın. Bir key, SDK'in zaten doldurmuş olabileceği bir konteyneri yeniden kullanmak yerine React'ın DOM düğümünü değiştirmesini zorlar:

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}
    />
  );
}

Ürün başlığı, rota slug'ı, veritabanı ID'si veya seçenek etiketi değil, seçilen çeşitliliğin SKU'ünü iletin. Seçim eksikse null görüntüleyin.

Next.js App Router yükleyici#

SDK'ı, ürün sayfalarını kapsayan en dar paylaşılan yerleşime bir kez yerleştirin. Next.js, bazı hidrasyonlardan sonra yüklenen betikler için afterInteractive'i dokümante eder:

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'ü bir yerleşimden bir kez görüntüleyin, ardından RoomVisualizerButton'ü çeşitlilik seçimini yöneten bir İstemci Bileşeni içinde görüntüleyin. NEXT_PUBLIC_ önekiyle başlayan değerler tarayıcıya gönderilir; bunları yalnızca Shop ID ve Publishable Key için kullanın.

Pages Router veya düz React için, betiği HTML kabuğunda bir kez oluşturun veya tek bir üst düzey etki kullanın:

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, bilinçli olarak ek bir geliştirme kurulum döngüsü gerçekleştirir, bu nedenle yinelenen kontrol gereklidir. Bireysel bir ürün bileşeni kaldırıldığında paylaşılan SDK etiketini kaldırmayın.

Gezinme, listeler ve çeşitlilikler#

İstemci tarafı rota değişiklikleri yerleşim betiğini yeniden yüklenmez. Aynı SKU birden fazla eş zamanlı bağlanmış görünümde belirebiliyorsa, her ürün denetimini kararlı rota kimliği ve SKU ile anahtarlayın. Izgaralar için her kartın kendi SKU'sü olmalıdır. Sonsuz kaydırma kart eklediğinde, React doğal olarak yeni temiz konteynerler bağlar.

Çeşitlilik seçimi için, selectedVariant.sku'ı ticaret durumunuzdan türetin ve productCode olarak iletin. Dokümante edilmemiş bir SDK yenileme yöntemini çağırmayın. Hızlı görüntüleme çekmeceleri ve rota geçişleri, işlenmiş DOM'ın bir sonraki ürüne sızmasını önlemek için önceki bileşenlerini kaldırmalıdır.

Eğer React hidrasyonu bir uyumsuzluk bildirirse, sunucu ve ilk istemci görüntülemesinin aynı olduğunu sağlayın. İstemci ticaret durumu SKU'ü çözümlenene kadar konteyner görüntülememek geçerlidir.

Ürün verilerini içe aktarma#

Ticaret arka ucunun kanonik çeşitlilik SKU'ünü ideal.house sku'e eşleyin. Ürün yükleme'yi kullanın, ardından ürünleri içe aktar, iş durumu, ürünleri listele, ürünleri güncelle, ürünü sil ve hatalar ve yeniden denemeler kılavuzlarına başvurun.

Herhangi bir arka uç kataloğ sorgusu, webhook, zamanlanmış senkronizasyon veya başlatma belirleyicisi hizmeti uygulama kodu olmaya devam eder; tarayıcı SDK bunu sağlamaz.

Doğrulama ve kaldırma#

Sunucu görüntüleme/hidrasyon, sert yükleme, istemci gezinme, tarayıcı Geri/İleri, çeşitlilik değişiklikleri, null/bilinmeyen SKU'lar, yinelenen kartlar, hızlı görüntüleme, Suspense/yükleme durumları, mobil, onay denetimleri ve üretim derlemesini test edin. Tek bir SDK isteğini ve tam DOM Ürün Kodu/SKU eşitliğini doğrulayın. Derlenen istemci paketlerini yanlışlıkla gizli anahtarlar açısından inceleyin.

Kaldırmak için, paylaşılan SDK bileşenini/etiketini ve tüm RoomVisualizerButton kullanımlarını silin, iki herkese açık ortam değişkenini kaldırın, yeniden derleyin ve SDK URL veya data-idealhouse-* işaretleme kalmadığını doğrulayın.