Интеграция Web SDK

Web SDK добавляет готовые интерфейсы ShopStory на сайт. Подключение состоит из настройки проекта со стороны ShopStory, установки скриптов и совместной проверки на домене клиента.

Если интерфейс полностью реализует клиент, используйте Public API. Для нативного приложения используйте Mobile SDK.

Что доступно​

• каталог прямых эфиров и записей;
• полноразмерный плеер;
• product mini-player на согласованных товарных страницах;
• уведомление об активном эфире, если оно включено для проекта;
• переход в карточку товара или согласованное действие корзины.

Доступные виджеты ShopStory включает в конфигурации проекта.

Контуры Web SDK​

Основной и PiP bundles имеют разные bootstrap-контракты. Не подключайте их на одной странице без схемы из integration handoff.

Модальное окно и плеер внутри страницы​

Контейнер в show() задаёт место каталога, а не полного плеера. При выборе эфира стандартный полный плеер открывается поверх страницы: на desktop — как модальное окно с затемнением, на mobile — на весь экран.

В showPlayer() нет параметра контейнера. Встраивание в собственное модальное окно сайта или inline-блок требует согласованного способа монтажа; не переносите player DOM и не меняйте positioning через произвольные CSS overrides. Параметры и ограничения методов: Web SDK reference.

До установки​

Передайте команде ShopStory:

1. Точные production- и test-домены.
2. URL страницы каталога эфиров.
3. Товарный фид и единый строковый feedProductId товара.
4. Примеры PDP, включая все используемые шаблоны.
5. Требуемое поведение кнопки «Купить».
6. Действующую CSP сайта и список целевых браузеров.

ShopStory регистрирует домены и origins, связывает их с applicationId, готовит конфигурацию и согласует способ определения товара на PDP. Проверку SDK на домене начинайте после подтверждения этой конфигурации.

Браузеры и маршрутизация до оценки​

Зафиксируйте в integration handoff версии браузеров и ОС для основной страницы, standalone PiP и целевых mobile browsers. Матрица относится к конкретным bundle и конфигурации проекта; согласуйте её до оценки QA и выпуска.

Для каждого целевого окружения проверьте загрузку каталога/PDP, live и VOD, первый кадр, продолжение видео, product action и возврат. Для SPA добавьте прямой вход, переход между PDP, смену SKU и back/forward: lifecycle Web SDK. Успешный API-запрос или script load не заменяет эту приёмку.

До загрузки SDK согласуйте consent flow. Для standalone PiP отдельно подтвердите commerce handlers и способ их регистрации; actions основного SDK не подключаются к нему автоматически.

Запустить каталог​

Получите applicationId и зарегистрируйте test origin до запуска. Скачайте Web SDK starter и разместите её на согласованном origin. Введите выданный ID; пример загружает production SDK и не содержит demo-данных или клиентских credentials.

Проверка результата: каталог показывает контент вашего проекта, выбранный VOD открывается, а сбой SDK оставляет страницу работоспособной. Пустой каталог сам по себе не подтверждает ошибку доступа: заранее согласуйте тестовый контент.

Разместить SDK в существующей странице​

Создайте контейнер:

<div id="shopstory"></div>

Подключите основной bundle и вызовите show() после его загрузки:

<script
  src="https://app.shopstory.live/sdk/shopstory-sdk/shopstory-sdk-v1.x.min.js"
  crossorigin="anonymous"
  charset="utf-8"
></script>

<script>
  const container = document.getElementById('shopstory');

  if (window.ShopStorySDK && container) {
    window.ShopStorySDK.show({
      containerElement: container,
      config: { clientId: 'assigned-application-id' },
    });
  }
</script>

v1.x — буквальная часть опубликованного имени web-bundle. Используйте этот URL без замены x и не конструируйте соседние адреса.

Этот URL является управляемым ShopStory release channel в рамках контракта v1, а не immutable client tag. Не копируйте bundle на свой CDN. ShopStory отвечает за выпуск и server-side rollback bundle; клиент должен уметь отключить loader своим feature flag или возвратом шаблона к состоянию без SDK. Контакт для уведомлений об изменениях и окно проверки фиксируются в integration handoff проекта.

Не добавляйте async или defer к основному bundle, если инициализация идёт следующим inline-скриптом. При отложенной загрузке вызывайте show() из собственного обработчика load.

Если script-src запрещает inline JavaScript, перенесите вызов show() в разрешённый same-origin файл либо используйте действующий nonce/hash сайта. Не добавляйте 'unsafe-inline' в script-src ради этого примера.

Как работает загрузка​

После выполнения основного bundle в window появляется ShopStorySDK. Вызов show() монтирует интерфейс в переданный контейнер. Затем SDK инициализируется, самостоятельно запрашивает каталог и товары и показывает результат. Клиенту не нужно повторять эти запросы через Public API.

При выборе эфира SDK загружает его данные и открывает полный плеер поверх страницы. Ниже показан сценарий с настроенным actions.addProductToCartById. Без обработчика корзины кнопка «Купить» открывает URL товара.

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

Методы и lifecycle​

show() монтирует каталог и возвращает void; он не подтверждает готовность видео. showPlayer() открывает заданный эфир. Параметры, TypeScript types и ограничения SPA: справочник Web SDK.

Product mini-player и live-уведомление​

Для согласованных страниц подключите отдельный bundle перед закрывающим </body>:

<script
  id="shopstory-pip"
  src="https://app.shopstory.live/sdk/shopstory-pip-sdk/shopstory-pip-sdk-v1.x.min.js"
  crossorigin="anonymous"
  charset="utf-8"
  async
></script>

Bundle запускает только компоненты, включённые для проекта. Для product mini-player ShopStory заранее фиксирует:

• какие страницы считаются PDP;
• где находится тот же feedProductId, что передан в товарном фиде;
• положение виджета и отступы от элементов сайта;
• профиль превью, условие показа после прокрутки, включение Live в PiP и Continuous Video;
• на каких страницах виджет должен быть отключён;
• какое действие выполняет кнопка «Купить».

Контейнер PiP скрипт создаёт сам и добавляет в document.body; отдельный <div> для виджета не требуется. Клиент обеспечивает доступность товарного ID в согласованном месте. ShopStory может использовать существующую разметку или другой согласованный источник ID; если подходящего источника нет, потребуется добавить его на PDP. Универсального обязательного data-* атрибута для всех сайтов нет.

PiP проверяет контент асинхронно и запрашивает товарное медиа только после положительного ответа API. При прямом входе на PDP это короткое превью записи или текущий live; при включённом Continuous Video переход из полного плеера позволяет продолжить просмотр на PDP. Профиль WebM с субтитрами, ориентир размера превью, режимы PiP, условия продолжения и ограничения autoplay описаны в режимах PiP на PDP. Порядок запросов и поведение без связанного эфира — в загрузке на PDP.

Standalone PiP bundle инициализируется без объекта actions из основного ShopStorySDK.show(). Вызов show() на другой странице не подключает callback к player, открытому из PiP. Для нового проекта такой player открывает URL товара; direct cart на этом пути требует отдельного commerce-контракта. Не загружайте основной и PiP bundles вместе на одной странице без явно проверенной схемы от ShopStory.

Ответ active от mini-player API означает, что сервер нашёл подходящий live или запись. В ручной API-интеграции открывайте body.stream.playerUrl без изменения и не собирайте его из данных видеопровайдера. Показ виджета на странице отдельно зависит от настройки DOM-шаблона PDP.

Покупательское действие​

Базовый вариант открывает URL товара. Добавление без перехода требует callback, который возвращает фактический результат клиентской корзины: Добавление в корзину.

Состояние кнопки до клика задаёт наличие. По умолчанию оно берётся из снимка фида; для остатка выбранного магазина в тот же объект actions передаётся обработчик наличия, а метод refreshProductsAvailability() обновляет карточки при смене магазина: Наличие и остатки.

Оба обработчика необязательны и независимы. Без них кнопка «Купить» открывает URL товара, а наличие остаётся по фиду.

Mobile​

В приложении ритейлера подключите Mobile SDK. Он принимает тот же feedProductId, управляет нативным video entrypoint и плеером, а действие с товаром передаёт router или cart-команде приложения.

Web-скрипты из этого раздела нельзя переносить в произвольный WebView. Доступ к пакету, точная совместимая версия, callbacks и приёмка передаются в integration handoff конкретного проекта.

Проверка перед production​

1. ShopStory подтвердил точные домены, applicationId и включённые компоненты.
2. Основной bundle загружается, window.ShopStorySDK определён до вызова show().
3. Каталог отображает контент нужного проекта.
4. Тестовый feedProductId точно совпадает со строковым значением в последней принятой версии фида.
5. Mini-player появляется только на согласованных PDP и не перекрывает критичные элементы.
6. Live-уведомление отображается только если оно включено и есть активный эфир.
7. Callback корзины показывает успех или ошибку из фактического ответа commerce-системы.
8. Страница остаётся работоспособной при сетевой ошибке ShopStory.
9. CSP разрешает согласованные ресурсы: CSP.
10. Проверены desktop и mobile web в целевых браузерах клиента.

Диагностика​

При обращении в поддержку передайте URL страницы, время возникновения проблемы, браузер, applicationId и фрагмент Console/Network без cookies, токенов и персональных данных.

Следующие шаги​

• Настроить аналитику

• Открыть справочник Web SDK

• Добавление в корзину

• Товарный фид

• Mobile SDK

• Mini-player API

• Безопасность