Интеграция React / Next.js#

Используйте браузерный SDK ideal.house непосредственно в React или Next.js. В этом руководстве нет отдельного пакета npm ideal.house React.

Статус проверки: Разметка SDK была проверена по текущему шаблону панели управления; официальная документация жизненного цикла/скриптов React и Next.js была проверена 7 сентября 2026 г. Клиентское приложение или учетные данные продакшена не были доступны, поэтому проверяйте собранное приложение от начала до конца.

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

Предварительные требования и границы#

Подготовьте Shop ID, Publishable Key, SKU, уже импортированный в каталог, и значение товара или варианта, формируемое на стороне клиента. Publishable Key может присутствовать в браузерной разметке. Храните Client Secret, ключи AI API и любые секретные учётные данные импорта товаров на сервере.

SDK обнаруживает DOM-контейнеры. React управляет моментом их монтирования; ваша интеграция отвечает за определение текущего варианта и замену контейнера при изменении его SKU.

Минимальные требования для подключения 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>

data-product-code должен точно совпадать с sku каталога ideal.house.

Компонент React#

Монтируйте новый контейнер каждый раз, когда код товара меняется. key заставляет React заменять узел DOM, а не переиспользовать контейнер, который SDK может уже заполнить:

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

Передавайте SKU выбранного варианта, а не название товара, слаг маршрута, идентификатор базы данных или метку опции. Если выбор неполный, отрисуйте null.

Загрузчик для Next.js App Router#

Разместите SDK один раз в наиболее узком общем макете, охватывающем страницы товаров. Next.js документирует afterInteractive для скриптов, которые загружаются после некоторой гидратации:

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 один раз из макета, затем отрисовывайте RoomVisualizerButton внутри клиентского компонента, который управляет выбором варианта. Значения с префиксом NEXT_PUBLIC_ отправляются в браузер; используйте их только для Shop ID и Publishable Key.

Для Pages Router или обычного React создайте скрипт один раз в оболочке HTML или используйте один верхнеуровневый эффект:

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);
}, []);

Strict Mode в React намеренно выполняет дополнительный цикл настройки в режиме разработки, поэтому проверка на дублирование обязательна. Не удаляйте общий тег SDK при размонтировании отдельного компонента товара.

Навигация, списки и варианты#

Изменение маршрута на стороне клиента не перезагружает скрипт макета. Используйте в качестве ключа каждого элемента управления товара стабильную идентичность маршрута плюс SKU, если один и тот же SKU может появляться в нескольких одновременно смонтированных представлениях. Для сеток каждая карточка требует своего SKU. Когда бесконечная прокрутка добавляет карточки, React естественно монтирует новые чистые контейнеры.

Получайте selectedVariant.sku из состояния платформы электронной коммерции и передавайте его как productCode. Не вызывайте недокументированный метод обновления SDK. При закрытии выдвижной панели быстрого просмотра или переходе между маршрутами размонтируйте предыдущий компонент, чтобы обработанный DOM не использовался для следующего товара.

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

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

Сопоставьте канонический вариант SKU бэкенда коммерции с ideal.house sku. Используйте Загрузка товаров, затем обратитесь к импорт товаров, статус задания, список товаров, обновление товаров, удаление товара и ошибки и повторные попытки.

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

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

Проверьте серверную отрисовку и гидратацию, полную загрузку страницы, навигацию на стороне клиента, кнопки браузера «Назад» и «Вперёд», смену вариантов, значения null и неизвестные SKU, повторяющиеся карточки, быстрый просмотр, Suspense и состояния загрузки, мобильную версию, управление согласием и сборку для рабочей среды. Убедитесь, что выполняется один запрос SDK, а код товара в DOM точно совпадает с SKU. Проверьте клиентскую сборку на случайно попавшие в неё секретные данные.

Для удаления интеграции удалите общий компонент или тег SDK и все использования RoomVisualizerButton, а также две публичные переменные окружения. Выполните сборку снова и убедитесь, что URL SDK и разметка data-idealhouse-* отсутствуют.