Интеграция Adobe Commerce / Magento Open Source#

Установите Room Visualizer через модуль Magento или пользовательскую тему и сопоставьте отображаемый SKU простого товара с каталогом ideal.house.

Статус проверки: Документация Adobe Commerce по клиентской части проверена 7 сентября 2026 г. Установка магазина клиента была недоступна. Темы Luma/Blank, Hyvä и PWA Studio используют разные стеки JavaScript; приведённый ниже пример предназначен для стандартного интернет-магазина на RequireJS.

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

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

Подготовьте тестовый экземпляр, пользовательский модуль или дочернюю тему, доступ к развёртыванию, Shop ID, Publishable Key и импортированные тестовые SKU. Никогда не изменяйте файлы в vendor/ или базовой теме. Hyvä и PWA Studio требуют собственного адаптера Alpine/React и не должны слепо копировать код RequireJS.

Минимальные требования для подключения 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, а не числовой идентификатор сущности Magento.

Добавьте блок на странице товара#

Создайте небольшой модуль или изменение макета темы для catalog_product_view. Свяжите блок с шаблоном .phtml, расположенным рядом с элементами действий над товаром. Шаблон позволяет безопасно вывести исходный SKU товара:

php

<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

Для настраиваемого товара исходный SKU страницы обычно совпадает с SKU родительского товара. Если визуальные материалы ideal.house относятся к дочерним простым товарам, сначала оставьте внешний контейнер пустым и заполняйте его только после определения выбранного простого товара.

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

Добавьте локальный инициализатор RequireJS в вашем модуле или теме. Инициализатор создаёт внешний скрипт и применяет все необходимые атрибуты данных перед его добавлением:

define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    var 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.appendChild(script);
  };
});

Инициализируйте его декларативно из шаблона, следуя рекомендуемому механизму text/x-magento-init от Adobe:

html

<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

Это создаёт тот же элемент SDK, что и минимальный контракт, без размещения учётных данных в URL RequireJS. Используйте в коде витрины только Publishable Key.

SKU выбранного варианта настраиваемого товара#

Стандартный виджет настраиваемого товара предоставляет состояние выбора через собственный компонент Magento, но переопределения темы могут менять его структуру. Реализуйте миксин RequireJS или обработчик в своём модуле в том месте, где тема определяет идентификатор простого товара. Сопоставьте этот идентификатор с его SKU по данным JSON, предоставленным сервером, и замените внешний контейнер:

function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

  var container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = sku.trim();
  host.appendChild(container);
}

Этот миксин и данные сопоставления идентификатора с SKU являются работой адаптера клиента. Не вычисляйте дочерний SKU по меткам опций и не документируйте событие или метод ideal.house, который не является частью публичного контракта SDK.

Динамический контент и кэши#

Пересоздавайте контейнер после смены образца цвета или материала, загрузки рекомендаций через AJAX, быстрого просмотра или замены внешнего контейнера персонализированным содержимым. Событие contentUpdated в Magento инициализирует компоненты Magento в добавленном содержимом; само по себе оно не предоставляет выбранный SKU, поэтому ваш адаптер должен определить и вывести правильный код.

После изменения кода выполните этапы развёртывания, подходящие для вашей среды, очистите кеши макетов, полных страниц и блоков и повторно разверните статические ресурсы. Проверьте работу с включёнными объединением и минификацией ресурсов для рабочей среды, а также Varnish/CDN.

Импорт данных товаров#

Сопоставьте SKU простых и дочерних товаров с sku в ideal.house. Используйте загрузку товаров и руководства по импорту, статусу задачи, получению списка, обновлению, удалению и повторным попыткам. Экспорт Magento, вызовы API администратора, задания cron и вебхуки клиент реализует в своих адаптерах.

Проверка и удаление#

Проверьте простые и настраиваемые товары, товары без SKU, отключённые дочерние товары и неизвестные SKU. Убедитесь, что SDK запрашивается один раз, SKU точно сопоставляется после каждого изменения образца или опции, а быстрый просмотр и рекомендации работают корректно. Проверьте мобильную вёрстку, выдачу из кеша, страницы для групп покупателей и управление согласием. Убедитесь, что секретные учётные данные отсутствуют в исходном коде и статических ресурсах.

Для удаления отключите/удалите пользовательский модуль или удалите файлы макета/шаблона/RequireJS дочерней темы, повторно разверните статический контент, очистите кэши и убедитесь, что SDK URL и контейнеры отсутствуют.