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

Это основной путь для новых клиентов: SDK запускается быстро и не требует ручной интеграции Public API на старте.

Для настройки прямого добавления в корзину см. Добавление в корзину (Short Flow).

Когда выбирать Web SDK

Web SDK подходит, когда нужен быстрый запуск с минимальными изменениями на сайте.

Если нужен полностью кастомный UI и своя серверная логика, используйте Quickstart.

Что включает SDK-путь

Страница каталога стримов через shopstory-sdk.
Mini-player и live-widget через shopstory-pip.
Mobile WebView-сценарий (wv=1, safe_area=1).

Автоматическое определение клиента

Никаких ID или ключей прописывать не нужно

SDK автоматически определяет вашу компанию по домену сайта, на котором он загружен. Например, если скрипт подключён на example.ru/live/, SDK определит клиента и подтянет его тему, контент и настройки — без передачи clientId, applicationId или других параметров.

CORS и маршрутизация API настраиваются на стороне ShopStory заранее — дополнительных действий на вашей стороне не требуется.

1) Список стримов (`shopstory-sdk`)

Создайте страницу, например https://example.ru/live, и добавьте контейнер:

live-container.html
<div id="shopstory"></div>

Подключите SDK и инициализацию:

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

<script type="application/javascript">
  (function () {
    "use strict";
    var ShopStorySDK = window.ShopStorySDK;
    if (ShopStorySDK) {
      ShopStorySDK.show({
        containerElement: document.getElementById("shopstory"),
      });
    }
  })();
</script>

Дополнительные методы SDK

Помимо show(), инстанс window.ShopStorySDK предоставляет два дополнительных метода:

`streamStatus(params)`

Получение текущего состояния трансляции.

stream-status.js
const status = await window.ShopStorySDK.streamStatus({
  clientId: "your-app-id",
  streamId: "1234"
});

console.log(status.state);        // "online" | "completed" | "confirmed" | "draft"
console.log(status.viewersCount);  // число текущих зрителей
console.log(status.likesCount);    // количество лайков

Возвращаемый объект содержит:

Поле	Тип	Описание
`state`	`string`	`draft`, `confirmed`, `online`, `completed`
`streamId`	`string`	ID трансляции
`viewersCount`	`number`	Текущие зрители
`likesCount`	`number`	Лайки
`messages`	`array`	Сообщения чата
`productHighlights`	`array`	Выделенные товары

`showPlayer(params)`

Открытие видеоплеера конкретного стрима.

show-player.js
await window.ShopStorySDK.showPlayer({
  clientId: "your-app-id",
  streamId: "1234"          // или null — создаст контейнер без воспроизведения
});

2) Mini-player и live-widget (`shopstory-pip`)

Вставьте скрипт в конец <body>:

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

Контракт поведения:

один скрипт поднимает два виджета сразу: mini-player и live-widget;
mini-player показывается в карточке товара, если для товара есть стрим/запись;
live-widget показывается только во время live;
скрипт можно размещать на страницах сайта, кроме cart/checkout (рекомендация);
один из виджетов можно отключить через менеджера/поддержку;
после закрытия пользователем mini-player не показывается повторно в течение 2 часов (per-device); для тестирования добавьте ?ignore-close-timestamp=1 к URL страницы.

Подключение mini-player для вашего сайта

Для корректной работы mini-player на страницах товаров ShopStory настраивает распознавание карточек товара под конкретный сайт клиента. Обратитесь к вашему менеджеру по интеграции или напишите на support@shopstory.live для подключения.

Для базового SDK-сценария ручные запросы к /v2/mini-player/* не обязательны.

3) Mobile WebView

Формат открытия стрима:

webview-url.txt
https://<client-domain>/live/?wv=1#/translation/<translationId>

Для устройств с вырезом:

webview-url-safe-area.txt
https://<client-domain>/live/?wv=1&safe_area=1#/translation/<translationId>

Контракт bridge-событий:

add-product — пользователь нажал «Купить»;
open-product — пользователь открыл карточку товара.

Реализация iOS/Android обработчиков: Deep links.

API-диагностика (опционально)

Проверка mini-player:

check-mini-player.sh
curl "https://app.shopstory.live/v2/mini-player/stream?application=<appId>&productCode=<sku>"

Проверка live-widget:

check-live-widget.sh
curl "https://app.shopstory.live/v2/mini-player/online?application=<appId>"

/v2/mini-player/stream может вернуть HTTP 200, 400 или 404 в зависимости от входных параметров и наличия стрима.

Чек-лист запуска

Скрипты shopstory-sdk и shopstory-pip загружаются со статусом 200.
На странице каталога присутствует контейнер #shopstory.
В карточке товара с релевантным SKU появляется mini-player.
Во время live появляется live-widget.
В мобильном WebView обработаны события add-product и open-product.
CORS настроен на стороне ShopStory — дополнительных действий не требуется. Если видите ошибки CORS в консоли браузера — обратитесь к вашему менеджеру.

Частые проблемы

Симптом	Причина	Действие
Mini-player не появляется	SKU/ID не совпадает с товарным фидом	Сверьте SKU/`feedProductId` и актуальность фида
Live-widget не показывается	Активного live нет	Проверьте `/v2/mini-player/online`
Контент перекрывается системной зоной в WebView	Не передан `safe_area=1`	Используйте URL с `?wv=1&safe_area=1#/translation/<translationId>`
Клик «Купить» в WebView не обрабатывается	Не реализован bridge	Подключите `add-product` и `open-product` в нативном слое
CORS-ошибка в консоли браузера	Домен сайта не добавлен в CORS-конфиг	Обратитесь к менеджеру ShopStory — настройка выполняется на нашей стороне
SDK-скрипт загружается, но `ShopStorySDK` — `undefined`	Атрибут `async` или `defer` на SDK-скрипте	Уберите `async`/`defer` с `shopstory-sdk` (только `shopstory-pip` загружается асинхронно)
Скрипт/API/изображения заблокированы браузером	Content Security Policy (CSP) на вашем сайте	Добавьте домены ShopStory в CSP — подробности в CSP Headers

Полный пример HTML-страницы

Минимальный шаблон с каталогом стримов и mini-player:

shopstory-live-page.html
<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Live — Ваш магазин</title>
  <style>
    #shopstory { width: 100%; min-height: 100vh; }
  </style>
</head>
<body>
  <div id="shopstory"></div>

  <!-- 1. Каталог стримов -->
  <script
    type="application/javascript"
    src="https://app.shopstory.live/sdk/shopstory-sdk/shopstory-sdk-v1.x.min.js"
    crossorigin="anonymous" charset="utf-8"
  ></script>
  <script type="application/javascript">
    (function () {
      "use strict";
      var sdk = window.ShopStorySDK;
      if (sdk) {
        sdk.show({
          containerElement: document.getElementById("shopstory"),
        });
      }
    })();
  </script>

  <!-- 2. Mini-player и live-widget (на все страницы, кроме checkout) -->
  <script
    id="shopstory-pip"
    type="application/javascript"
    src="https://app.shopstory.live/sdk/shopstory-pip-sdk/shopstory-pip-sdk-v1.x.min.js"
    crossorigin="anonymous" charset="utf-8" async
  ></script>
</body>
</html>

Следующие разделы

Deep links
Mini-player
Feed Requirements
CSP Headers — если на вашем сайте настроена Content Security Policy

Когда выбирать Web SDK​

Что включает SDK-путь​

Автоматическое определение клиента​

1) Список стримов (shopstory-sdk)​

Дополнительные методы SDK​

streamStatus(params)​

showPlayer(params)​

2) Mini-player и live-widget (shopstory-pip)​

3) Mobile WebView​

API-диагностика (опционально)​

Чек-лист запуска​

Частые проблемы​

Полный пример HTML-страницы​

Следующие разделы​