Ideal House
Перейти к содержанию

Интеграция WooCommerce#

Добавьте кнопки Room Visualizer на страницы продуктов WooCommerce и синхронизируйте код продукта ideal.house с выбранным SKU варианта.

Статус проверки: Документация и общедоступное поведение WooCommerce проверены 7 сентября 2026 г. Эта реализация не прошла проверку в магазине клиента. Классические шаблоны, блочные темы, расширения вариантов товаров и плагины быстрого просмотра могут создавать разный DOM; проверьте используемую вами комбинацию на тестовом сайте.

Перед загрузкой SDK: Откройте Панель управления → Настройки, добавьте источник вашего интернет-магазина в Allowed Origins (CORS) и нажмите Сохранить. Укажите опубликованное имя хоста, а также источники используемых сред предпросмотра и тестирования; разделяйте несколько источников запятыми. См. инструкцию по настройке.

Область применения и требования#

Это руководство предназначено для WooCommerce на WordPress. В нём используются небольшой плагин для вашего сайта или дочерняя тема, стандартный механизм загрузки ресурсов WordPress и хуки товаров WooCommerce. Готовый устанавливаемый плагин ideal.house для WordPress не предоставляется.

Подготовьте доступ администратора и файлов, Shop ID, Publishable Key и импортированные записи ideal.house для каждого визуализируемого SKU. Присвойте каждому простому продукту и каждой поддерживаемой вариации непустой уникальный SKU в WooCommerce.

Минимальная разметка SDK#

Это публичный контракт 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>

Код в создаваемом контейнере должен совпадать с sku товара, импортированного в каталог. Не помещайте идентификаторы базы данных WooCommerce в data-product-code, если вы намеренно не использовали их как SKU в каталоге.

Загрузите SDK один раз#

Добавьте этот код в functions.php дочерней темы или в плагин, разработанный для вашего сайта. Замените значения-заполнители.

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

Если вы поддерживаете WooCommerce на WordPress версий до 6.3, передайте true последним аргументом функции подключения скрипта и добавьте async через фильтр.

Создайте контейнер на странице товара#

Следующий хук размещает внешний контейнер после формы добавления в корзину. Для простых товаров SKU задаётся сразу. Для вариативных товаров контейнер сначала остаётся пустым; браузерный адаптер заполняет его, когда покупатель полностью выберет вариант товара.

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>' : ''
    );
});

Убедитесь, что этот хук присутствует в вашем шаблоне товара. Если тема заменяет шаблон WooCommerce или блок коллекции товаров, может потребоваться интеграция с блоками или другой документированный хук WooCommerce.

Синхронизация выбранной вариации#

Стандартная форма выбора вариантов WooCommerce вызывает события жизненного цикла вариантов через jQuery. Добавьте локальный файл, например assets/js/idealhouse-woocommerce.js, подключите его с зависимостями jquery и wc-add-to-cart-variation и используйте следующий код:

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

Этот файл — адаптер WooCommerce, который разрабатывает клиент. Если плагин вариантов заменяет стандартный скрипт формы, используйте документированный обработчик выбора этого плагина: нельзя предполагать, что прежние события по-прежнему срабатывают. Не ограничивайтесь изменением атрибута контейнера, уже обработанного SDK; замените его чистым контейнером.

Сетки товаров, быстрый просмотр и AJAX-навигация#

Для карточек каталога используйте хук цикла товаров, например woocommerce_after_shop_loop_item, и выводите SKU простого товара. Для вариативных товаров в сетке конкретный вариант обычно ещё не выбран; добавьте ссылку на страницу товара или реализуйте отдельный адаптер выбора варианта.

Плагины быстрого просмотра и блоки WooCommerce могут добавлять товары после первоначальной загрузки страницы. Разместите внешний контейнер в используемом ими шаблоне и вызывайте вашу связующую функцию render() из документированного обработчика завершения отрисовки этого инструмента. Если стабильного обработчика нет, можно обнаруживать новые узлы .idealhouse-host с помощью MutationObserver, ограниченного нужной областью, однако за его производительность и жизненный цикл отвечает клиент.

Сопоставление данных каталога и импорт#

Сопоставьте WC_Product::get_sku() и каждый WC_Product_Variation::get_sku() с sku в ideal.house. Родительские и дочерние товары не должны использовать один код, если им соответствуют разные визуальные материалы.

WooCommerce автоматически не отправляет изменения каталога в ideal.house. Используйте Загрузку продукта и относящиеся руководства по импорту, статусу задачи, списку, обновлениям, удалению и обработке повторных попыток. Любая запланированная экспортная процедура или мост вебхуков является реализацией заказчика.

Проверка перед запуском#

  1. Проверьте простой товар, вариативный товар, товар без SKU и товар с SKU, отсутствующим в ideal.house.
  2. Убедитесь, что SDK запрашивается один раз, а тег скрипта сохраняет оба атрибута с учётными данными.
  3. Выберите каждый вариант и убедитесь, что data-product-code совпадает с SKU этого варианта.
  4. Сбросьте форму вариации; старый контейнер должен исчезнуть.
  5. Где применимо, проверьте сетку товаров, быстрый просмотр, AJAX-фильтры, динамические фрагменты корзины, закреплённую кнопку добавления в корзину на мобильных устройствах и кнопки браузера «Назад» и «Вперёд».
  6. Проверьте работу без входа в учётную запись, с включёнными средствами управления согласием и кешированием, используемым на рабочем сайте.
  7. Убедитесь, что Client Secret не появляется в HTML, JavaScript, журналах или картах исходного кода.

Удаление интеграции#

Удалите хуки и фильтр PHP, а также подключение локального адаптера вариантов. Удалите внешние контейнеры из переопределённых шаблонов или блоков, очистите временный кеш WooCommerce и кеши страниц и CDN. Убедитесь, что запросы SDK и элементы data-idealhouse-* больше не появляются.

Официальные ссылки платформы#