Методы интеграции
До установки команда ShopStory подтверждает applicationId, единый feedProductId, источник товарных данных и компоненты проекта. Источником может быть фид, API магазина или их сочетание. Для 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 не означает, что этот виджет уже включён.
Подготовку выгрузки описывает раздел Товарный фид, чтение товаров через API — Интеграция с интернет-магазином. После этого подключите 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, навигация, авторизация, корзина и результат покупки остаются в приложении.
Нативный API SDK управляет встроенным WebView-плеером. Приложение предоставляет свои экраны и контейнеры; создавать собственный WebView или bridge не требуется. Архитектура и доступность iOS, Flutter и Android: SDK и WebView, платформенная поставка.
Клиентская команда:
- передаёт тот же строковый
feedProductId, что используется в выбранном источнике товарных данных; - встраивает SDK в существующий native navigation и lifecycle;
- обрабатывает типизированное действие с товаром через свой router или cart-команду;
- подтверждает успех корзины только по ответу своей commerce-системы;
- выпускает и при необходимости откатывает согласованную версию пакета.
В integration handoff ShopStory указывает доступ к пакету, точную совместимую версию, applicationId, тестовые товары и checklist для этой версии. Доступ к пакету, клиентские routes и параметры rollout публично не размещаются.
Для mobile-интеграции используйте Mobile SDK. Формат выгрузки описан в товарном фиде, товарный API и варианты — в интеграции с интернет-магазином. Для прямой корзины дополнительно используйте контракт добавления товара.
Commerce-интеграции
Покупательское действие подключается следующими способами:
- Открытие карточки товара — базовый сценарий: на web через URL, в Mobile SDK через нативный route по
feedProductId. - Добавление в корзину без перехода: на web используется callback клиента, в Mobile SDK — типизированное действие host app.
- Показ наличия по выбранному магазину до клика — штатный обработчик наличия Web SDK.
- Товарные данные через API, выбор SKU в плеере, персональная цена и формы получения подключаются через расширенный commerce-контракт.
Commerce-система клиента определяет применимые магазин и способ доставки, проверяет цену и остаток и подтверждает результат добавления в корзину. ShopStory не рассчитывает эти значения. Расширенный контракт описывает отображение условий магазина и работу с вариантами; штатный обработчик наличия цену не меняет.
Для расширенного сценария получите комплект подключения SDK с версией, регистрацией обработчиков и запускаемым примером. Подробные контракты: Добавление в корзину, Наличие и остатки и Интеграция с интернет-магазином.
Матрица решения
| Требование | Web SDK | Public API | Mobile SDK | Custom commerce |
|---|---|---|---|---|
| Готовый web-каталог и плеер | Да | Клиент реализует UI | Нет | Нет |
| Product video на PDP | Web mini-player после настройки | Клиент реализует UI | Native entrypoint и player | Нет |
| Полный контроль собственного интерфейса | Ограниченный | Да | Экраны, контейнеры и navigation — у клиента; player/WebView — у SDK | По контракту |
| Прямая корзина | 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 принимает другой внутренний ключ, преобразуйте его один раз на границе системы ритейлера.