Методы интеграции
До установки команда ShopStory подтверждает applicationId, единый feedProductId, доступ к фиду и компоненты проекта. Для Web SDK и browser-side Public API также согласуются домены и origins.
Web SDK
Используйте Web SDK для готового каталога эфиров, плеера, product mini-player и live-уведомления на сайте.
Клиентская команда:
- размещает согласованные SDK-скрипты;
- предоставляет контейнер для каталога;
- добавляет разрешённые ShopStory origins в CSP;
- сохраняет товарный ID в верстке в согласованном формате;
- проверяет итоговый UX на своих шаблонах и браузерах.
ShopStory:
- регистрирует домены и конфигурацию проекта;
- связывает домен с
applicationId; - настраивает тему и доступный набор виджетов;
- согласует способ определения товара на PDP;
- поддерживает интерфейс и обновления плеера.
Mini-player требует отдельной настройки под шаблон товарной страницы. Сам факт загрузки SDK не означает, что этот виджет уже включён.
Подготовку данных описывает раздел Товарный фид. После этого подключите Web SDK и нужное действие корзины.
Public API
Public API подходит, когда клиент строит собственный список эфиров и записей или сам управляет состояниями интерфейса.
Клиентская команда отвечает за:
- HTTP-клиент и тайм-ауты;
- проверку транспортного кода и JSON-конверта;
- состояния загрузки, пустой выдачи и ошибки;
- собственный UI, аналитику и доступность;
- корректную работу при временной недоступности ShopStory.
API можно вызывать с сервера клиента. Запрос из браузера возможен после регистрации точного origin в ShopStory. applicationId передаётся в запросе как идентификатор проекта и не считается секретом.
Первый запрос описан в Quickstart. Форматы и методы собраны в разделах Формат ответов, Каталог эфиров и Mini-player API.
Mobile SDK
Mobile SDK встраивает live, записи и product video в нативное приложение ритейлера. SDK управляет воспроизведением и media lifecycle. PDP, навигация, авторизация, корзина и результат покупки остаются в приложении.
Клиентская команда:
- передаёт тот же строковый
feedProductId, что используется в товарном фиде; - встраивает SDK в существующий native navigation и lifecycle;
- обрабатывает типизированное действие с товаром через свой router или cart-команду;
- подтверждает успех корзины только по ответу своей commerce-системы;
- выпускает и при необходимости откатывает согласованную версию пакета.
В integration handoff ShopStory указывает доступ к пакету, точную совместимую версию, applicationId, тестовые товары и checklist для этой версии. Доступ к пакету, клиентские routes и параметры rollout публично не размещаются.
Для mobile-интеграции обязательны товарный фид и Mobile SDK. Для прямой корзины дополнительно используйте контракт добавления товара.
Commerce-интеграции
Есть три способа подключить покупательское действие:
- Переход на URL карточки товара из ShopStory — базовый сценарий.
- Добавление в корзину без перехода: на web используется callback клиента, в Mobile SDK — типизированное действие host app.
- Показ наличия по выбранному магазину до клика — штатный обработчик наличия Web SDK.
- Нестандартный cart API или вызов со стороны ShopStory — отдельная интеграционная работа.
Commerce-система клиента определяет применимые магазин и способ доставки, проверяет цену и остаток и подтверждает результат добавления в корзину. ShopStory не рассчитывает эти значения.
Подробнее: Добавление в корзину, Наличие и остатки и Кастомные commerce-интеграции.
Матрица решения
| Требование | Web SDK | Public API | Mobile SDK | Custom commerce |
|---|---|---|---|---|
| Готовый web-каталог и плеер | Да | Клиент реализует UI | Нет | Нет |
| Product video на PDP | Web mini-player после настройки | Клиент реализует UI | Native entrypoint и player | Нет |
| Полный контроль собственного интерфейса | Ограниченный | Да | Native shell и navigation у клиента | По контракту |
| Прямая корзина | Callback клиента | В коде клиента | Native product action | Адаптер к нестандартному API |
| Наличие по выбранному магазину до клика | Обработчик наличия в actions | В коде клиента | По контракту поставленной версии пакета | Серверный посредник, если stock API закрыт для покупателя |
| Окончательная проверка при покупке | Выполняет cart-команда клиента | Выполняет commerce-код клиента | Выполняет приложение клиента | Адаптер к нестандартному API |
| Основная поверхность | Web | Собственный web или server-side UI | Native mobile | Commerce-система клиента |
Методы можно сочетать: например, Web SDK на сайте, Mobile SDK в приложении и Public API для собственного каталога. Во всех поверхностях используйте один строковый feedProductId. Если commerce API принимает другой внутренний ключ, преобразуйте его один раз на границе системы ритейлера.