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

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

Используйте собственное приложение интернет-магазина Ecwid и документированный жизненный цикл его JS API, чтобы добавить элементы управления Room Visualizer на страницы товаров Ecwid.

Статус проверки: Документация JS API интернет-магазина Ecwid проверена 7 сентября 2026 г. Приложение Ecwid и тестовый магазин продавца были недоступны. Перед развёртыванием сверьте точные поля данных страницы с актуальной справкой OnPageLoaded.

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

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

Для постоянной настройки интернет-магазина Ecwid требуется собственное приложение с файлом JavaScript, который вы размещаете на своём хостинге. Подготовьте магазин и приложение Ecwid для разработки, файл адаптера, доступный по HTTPS, Shop ID, Publishable Key и импортированные SKU товаров и вариантов.

Если Ecwid встроено в другой CMS, пользовательское приложение витрины остается надежным местом для кода, так как оно работает с витриной Ecwid. Скрипт родительской страницы может не разделять тот же жизненный цикл или документ во всех режимах встраивания.

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

Используйте точный Ecwid SKU, который вы импортировали, в качестве ideal.house sku.

Инициализация вашего приложения витрины Ecwid#

Следуйте руководству быстрого старта Ecwid по настройке интернет-магазина, чтобы зарегистрировать файл, размещённый на своём хостинге. Запустите его из документированного обработчика готовности API, затем загрузите SDK ideal.house один раз:

js
Ecwid.OnAPILoaded.add(function () {
  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);
});

Для приложения с несколькими магазинами получайте два публичных значения ideal.house из безопасной публичной конфигурации вашего приложения. Никогда не помещайте секрет приложения Ecwid, токен доступа или ideal.house Client Secret в этот файл.

Отрисовка на страницах товаров#

Ecwid документирует Ecwid.OnPageLoaded.add() и передаёт обработчику информацию о странице. По актуальной справке API уточните тип и идентификатор страницы товара, запросите или прочитайте данные товара через поддерживаемый клиентский интерфейс Ecwid, затем передайте определённый SKU в следующую функцию:

js
function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Вставьте host в стабильное место страницы с подробной информацией о товаре после того, как Ecwid завершит её отрисовку. Удаляйте предыдущий внешний контейнер при изменении типа страницы. Селектор DOM и поиск товара по данным страницы клиент реализует в своём адаптере, поскольку макеты магазина и версии данных Ecwid могут меняться.

Опции и навигация#

Когда покупатель выбирает опции товара, дождитесь, пока Ecwid определит доступный для покупки вариант и его SKU. Вызовите mountIdealhouse() с этим SKU или очистите внешний контейнер, если выбор не завершён. Не составляйте код путём объединения подписей опций.

Ecwid — одностраничный интернет-магазин. Используйте документированный жизненный цикл страниц (обработчики OnPageLoaded и переключения страниц), а не только событие браузера DOMContentLoaded. При переходах между категориями и результатами поиска, использовании кнопок браузера «Назад» и «Вперёд», встроенных виджетов и всплывающих окон товаров удаляйте устаревшие внешние контейнеры и после отрисовки создавайте новый контейнер.

Импорт товаров#

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

Экспорт через Ecwid REST API, вебхуки, установку с использованием OAuth и регулярную синхронизацию клиент реализует самостоятельно на сервере с соответствующей авторизацией Ecwid.

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

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

Для удаления интеграции отсоедините размещённый на вашем хостинге файл JavaScript от собственного приложения или удалите приложение. Удалите добавленные внешние контейнеры и обработчики. После навигации по магазину и полной перезагрузки страницы убедитесь, что URL SDK и все узлы data-idealhouse-* исчезли.

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