Ideal House
İçeriğe atla

WooCommerce entegrasyonu#

WooCommerce ürün sayfalarına Room Visualizer düğmeleri ekleyin ve ideal.house ürün kodunu seçilen varyasyon SKU ile senkronize tutun.

Doğrulama durumu: Belge ve herkese açık WooCommerce davranışı 7 Eylül 2026 tarihinde gözden geçirildi. Bu uygulama bir müşteri mağazasında sertifikalandırılmamıştır. Klasik şablonlar, blok temalar, varyasyon uzantıları ve hızlı görüntüleme eklentileri farklı DOM oluşturabilir; tam yığını geçici ortamda test edin.

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

Kapsam ve ön koşullar#

Bu kılavuz, WordPress üzerindeki WooCommerce'ı hedef alır. Küçük bir siteye özel eklenti veya alt tema, standart WordPress varlık yükleyicisi ve WooCommerce ürün kancaklarını kullanır. Kurulabilir bir ideal.house WordPress eklentisi değildir.

Yönetici ve dosya erişimi, Shop ID, Publishable Key ve görüntülenebilir her SKU için içiçe aktarılmış ideal.house kayıtlarını hazırlayın. Her basit ürüne ve desteklenen her varyasyona WooCommerce içinde boş olmayan, benzersiz bir SKU verin.

Minimal SDK işaretleme dili#

Entegrasyon tarafından kullanılan herkese açık SDK sözleşmesi şudur:

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>

Üretilen konteyner kodu, içiçe aktarılmış katalog sku ile eşleşmelidir. Bu kimlikleri katalog SKU'ları olarak bilinçli olarak kullanmadıkça, WooCommerce veritabanı kimliklerini data-product-code içine koymayın.

SDK'ü bir kez yükleyin#

Bu kodu bir alt tema functions.php'sına veya siteye özel bir eklentiye ekleyin. Yer tutucuları değiştirin.

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

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

6.3'ten önceki WordPress sürümlerinde WooCommerce destekliyorsanız, son yükleme argümanı olarak true geçirin ve filtreye async ekleyin.

Ürün sayfası ana evreni oluştur#

Aşağıdaki kanca, bir ana evreni sepete ekleme formunun ardından yerleştirir. Basit ürünler SKU'lerini derhal alır. Değişken ürünler boş başlar; tarayıcı adaptörü, tam bir varyasyon seçildiğinde onları doldurur.

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

Kancanın ürün şablonunuzda mevcut olduğunu doğrulayın. WooCommerce şablonunu veya Ürün Koleksiyonu bloğunu değiştiren bir tema, bir blok entegrasyonu veya başka bir belgelenmiş WooCommerce kancası gerektirebilir.

Seçilen bir varyasyonu senkronize edin#

WooCommerce'ün paketlenmiş varyasyon formu, jQuery varyasyon yaşam döngüsü olaylarını tetikler. Örneğin assets/js/idealhouse-woocommerce.js gibi yerel bir dosya ekleyin, jquery ve wc-add-to-cart-variation bağımlılıklarıyla yükleyin ve şunu kullanın:

js
(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

Bu dosya, müşteriye ait bir WooCommerce adaptörüdür. Bir varyasyon eklentisi standart form betiğini değiştiriyorsa, bu olayların hâlâ tetiklendiğini varsaymak yerine o eklentinin belgelenmiş seçim geri çağrımını kullanın. SDK tarafından zaten işlenmiş bir konteynerin yalnızca özniteliğini güncellemeyin; temiz bir konteynerle değiştirin.

Ürün ızgaraları, hızlı görüntüleme ve AJAX gezinme#

Katalog kartları için, basit ürün SKU'sini oluşturmak için woocommerce_after_shop_loop_item gibi bir ürün döngüsü kancası kullanın. Izgaradaki değişken ürünlerin genellikle çözümlenmiş bir varyasyonu yoktur; ürün sayfasına bağlantı verin veya açık bir varyasyon seçici adaptörü oluşturun.

Hızlı görüntüleme eklentileri ve WooCommerce Blokları, ilk sayfa yüklemesinden sonra ürünler enjekte edebilir. Ana evreni oluşturdukları şablona yerleştirin ve render() köprüsünü o aracın belgelenmiş tamamlama geri çağrımından çalıştırın. Kararlı bir geri çağrım yoksa, kapsamlı bir MutationObserver yeni .idealhouse-host düğümlerini algılayabilir, ancak performansı ve yaşam döngüsü müşteriye aittir.

Katalog eşleme ve içe aktarma#

WC_Product::get_sku()'i ve her WC_Product_Variation::get_sku()'yi ideal.house sku'e eşleyin. Farklı görsel varlıkları temsil ediyorsa, ana ve alt ürünler bir kod paylaşmamalıdır.

WooCommerce, katalog değişikliklerini otomatik olarak ideal.house'e itmez. Ürün yükleme ve içe aktarma, iş durumu, listeleme, güncellemeler, silme ve yeniden deneme yönetimi kılavuzlarını kullanın. Herhangi bir zamanlanmış dışa aktarma veya webhook köprüsü müşteri uygulamasıdır.

Başlamadan önce doğrulayın#

  1. Bir basit ürün, bir değişken ürün, eksik bir SKU ve ideal.house'de olmayan bir SKU test edin.
  2. SDK'in bir kez istendiğini ve betik etiketinin her iki kimlik bilgisi özniteliğini koruduğunu doğrulayın.
  3. Her varyasyonu seçin ve data-product-code'ün varyasyon SKU'e eşit olduğunu doğrulayın.
  4. Varyasyon formunu sıfırlayın; eski konteyner kaybolmalıdır.
  5. Bir ürün ızgarası, hızlı görüntüleme, AJAX filtreleri, sepet parçacıkları, mobil sabit sepete ekleme ve uygunsa tarayıcı Geri/İleri'yi test edin.
  6. Çıkış yapılmış durumdayken, onay denetimleri ve üretim önbelleği etkinleştirilerek test edin.
  7. Client Secret'ün HTML, JavaScript, günlüklerde veya kaynak haritalarında görünmediğini kontrol edin.

Entegrasyonu kaldırın#

PHP kanca/filtrelerini ve yerel varyasyon adaptörü yüklemesini kaldırın. Ana evrenleri aşırı yüklenmiş şablonlardan veya bloklardan silin, WooCommerce geçici verilerini ve sayfa/CDN önbelleklerini temizleyin, ardından SDK istemi veya data-idealhouse-* öğesi kalmadığını doğrulayın.

Resmi platform referansları#