BigCommerce entegrasyonu#

SDK'i bir kez yükleyerek ve mevcut ürün veya varyant SKU'ü oluşturulan düğme kapsayıcısına işleyerek Room Visualizer'i BigCommerce Stencil mağaza vitrinine ekleyin.

Doğrulama durumu: BigCommerce geliştirici dokümantasyonu 7 Eylül 2026 tarihinde incelendi. Test mağazası mevcut değildi. Stencil ve Catalyst farklı işleme ve gezinme modellerine sahiptir; bu kılavuz uygulanabilir bir Stencil yolu sağlar ve Catalyst mağaza vitrinlerini bir çerçeve adaptörüne yönlendirir.

SDK'yı yüklemadan önce: Panel → Ayarlar açın, mağaza vitrininiz kökenini Allowed Origins (CORS)'e ekleyin ve Kaydet'e tıklayın. Yayımlanan ana bilgisayar adını ve kullandığınız önizleme veya geçici kökenleri dahil edin; birden fazla kökeni virgüllerle ayırın. yapılandırma adımları bölümüne bakın.

Bir mağaza vitrini yolu seçin#

Stencil: yükleyiciyi Script Manager veya Scripts API ile kurun, ardından kapsayıcıyı özel bir tema şablonuna ekleyin.
Catalyst: betiği ve bileşeni Catalyst React/Next.js uygulamasına ekleyin; React / Next.js kılavuzunu izleyin.
Eski Blueprint: desteklenen bir mağaza vitrinine geçiş yapın veya bir BigCommerce geliştiricinin güvenli bir ekleme noktasını belirlemesini sağlayın. Güncel Scripts API dokümantasyonu Blueprint'i ayrı olarak ele alır.

Tema düzenleme erişimi, bir geçici tema/kanal, ideal.house Shop ID ve Publishable Key ile ideal.house'ya içe aktarılmış en az bir BigCommerce SKU'e ihtiyacınız var.

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>

Kapsayıcının Ürün Kodu, içe aktarılan kataloğ sku ile tam olarak eşleşmelidir. Bu kılavuz bir ideal.house BigCommerce uygulaması varsaymaz.

Stencil'de kurulum#

Mağaza Vitrini → Script Manager içinde, ilgili mağaza vitrini/kanalı ve ürün sayfaları için bir alt bilgi betiği oluşturun. Örnekten yalnızca tarayıcı güvenli kimlik bilgilerinizle SDK betik etiketini yapıştırın. Script Manager, kanal duyarlı Scripts API'in kontrol paneli karşılığıdır.

Yeniden kullanılabilir bir uygulama için, bunun yerine BigCommerce'ın Scripts API'ini kullanın. Bu API işlemi ve uygulama OAuth akışı entegrasyon hizmetinizin sorumluluğundadır; erişim jetonunu mağaza vitrini kodunda ifşa etmeyin.

Yalnızca bir SDK etiketi olduğundan emin olun. templates/layout/base.html içinde de dahil etmeyin.

İlk ürünü işleyin#

Özel bir Stencil temasında, temanızın kullandığı ürün görüntüsü kısmi şablonunda, kapsayıcıyı ürün formunun yakınına ekleyin:

handlebars

{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

Kesin kısmi şablon temaya göre değişir. Özelleştirilen temayı önizlemek için Stencil CLI'ı kullanın ve mağaza vitrini tarafından oluşturulan HTML'ü düzenlemek yerine değişikliği sürüm kontrollü bir temada tutun.

Kartlar için, kapsayıcıyı yalnızca kart bağlamı içe aktardığınız kesin SKU'i açığa çıkardığında işleyin. Seçenekleri olan bir ürün, kategori sayfasında nihai bir varyant SKU'a sahip olmayabilir; alıcı tam bir varyant seçmedikçe ürün sayfasına bağlantı verin.

Ürün seçeneklerini eşitleyin#

Stencil tema JavaScript'sı, ürün seçenek değişikliklerini temaya özgü ürün ayrıntıları kodu aracılığıyla alır. Mevcut temanın nihai varyant yanıtını çözdüğü noktada bir müşteri adaptörü ekleyin:

export function replaceIdealhouseContainer(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);
}

Çözülen varyant SKU'i tema geri çağırmanızdan geçirin. BigCommerce temaları varsayılan ürün ayrıntıları uygulamasını özelleştirebilir veya değiştirebilir, bu nedenle bu kılavuz küresel bir seçenek-değişikliği olayı icat etmez. Yeniden eklemeden önce eski kapsayıcıyı kaldırın.

Hızlı görüntüleme ve dinamik sayfalar#

Hızlı Görüntüleme, çok yönlü arama, sayfalama ve istemci tarafı gezinme, ürün DOM'ünü değiştirebilir. Her işlenen şablona temiz bir kapsayıcı ekleyin ve temanın belgelenmiş işleme geri çağırmasından sonra aynı köprüyü çağırın. Zaten SDK tarafından doldurulmuş bir kapsayıcıyı klonlamayın.

Catalyst, istemci tarafı React işleme kullanır ve Stencil Handlebars bağlamına sahip değildir. SDK'i uygulama kabuğunda bir kez yükleyin ve görselleştirici bileşenini, React/Next.js kılavuzunda gösterildiği gibi, seçilen varyant SKU'a göre anahtarlayın.

Ürün verisini içe aktarın ve eşleştirin#

BigCommerce sku değerlerini ideal.house sku'ya eşleştirin; varyantlar için ana ürün kimliği yerine her varyant SKU'ını kullanın. BigCommerce kataloğu verisi, tarayıcı SDK tarafından eşitlenmez.

Onaylanmış içe aktarma sözleşmesi için Ürün yükleme 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 bölümlerini kontrol edin. Herhangi bir BigCommerce API dışa aktarma, web kancası veya planlanmış eşitleme, müşteri tarafından işletilen bir adaptördür.

Doğrulayın ve kaldırın#

Yayına almadan önce, basit bir ürünü, her seçenek kombinasyonunu, SKU olmayan bir ürünü ve ideal.house'da olmayan bir SKU'yi test edin. Ürün sayfasını, kategori kartlarını, Hızlı Görüntüleme'yi, çok yönlü gezinmeyi, tarayıcı Geri/İleri'yi, mobil yerleşimi, onay davranışını ve her etkin mağaza vitrini kanalını kontrol edin. DevTools'ta, başarılı bir SDK isteğinin ve kesin bir Ürün Kodu/SKU eşleşmesinin doğrulayın.

Entegrasyonu kaldırmak için, Script Manager girdisini veya Scripts API kaydını silin, tüm tema kapsayıcı işaretleme ve adaptör kodunu kaldırın, temiz temayı yayınlayın, ardından mağaza vitrini/CDN önbelleklerini temizleyin. Her kanalda SDK isteğinin bulunmadığını doğrulayın.