Web SDK: методы и lifecycle

Для первого подключения используйте Web SDK. Здесь собран контракт методов основного bundle.

Методы основного SDK​

Параметр SDK clientId принимает тот же идентификатор проекта, который в Public API называется applicationId. Используйте значение, выданное ShopStory, без преобразований. Общие правила: Идентификаторы.

show​

Монтирует каталог в контейнер сайта. Возвращает undefined (тип void), не предоставляет Promise загрузки каталога.

await ShopStorySDK.show(...) не ждёт каталог. Ограничения повторной инициализации описаны в разделе SPA и lifecycle.

showPlayer​

Открывает указанную трансляцию в собственном контейнере в document.body. При первом вызове SDK создаёт контейнер, при следующих использует его повторно. Оба параметра обязательны:

Возвращает Promise<void>. Promise завершается после внутренней инициализации SDK, ещё до подтверждения загрузки данных эфира и воспроизведения видео. Использовать его как сигнал «видео готово» нельзя.

async function openShopStoryPlayer(streamId) {
  const sdk = window.ShopStorySDK;
  if (!sdk) {
    console.error('Основной bundle ShopStory не загружен');
    return;
  }

  try {
    await sdk.showPlayer({
      clientId: 'assigned-application-id',
      streamId,
    });
  } catch (error) {
    console.error('Не удалось вызвать плеер ShopStory', error);
  }
}

Передавайте идентификаторы строками. Список трансляций для собственного интерфейса получайте через GET /v3/streams.

showPlayer() не принимает actions и cartUrl и не наследует их из ранее вызванного show(). Для прямой корзины используйте плеер внутри каталога, созданного через show({ actions, ... }), либо согласованный commerce-контракт.

Готовность и ошибки​

У основного SDK нет публичных событий или параметров onReady / onError для загрузки каталога и плеера. Событие load у <script> позволяет начать инициализацию; готовность каталога или видео оно не подтверждает.

try/catch в примере не перехватывает все ошибки загрузки и воспроизведения. При сбое до завершения инициализации Promise showPlayer() может остаться незавершённым. Не связывайте с ним разблокировку страницы, корзины или других функций сайта.

Состояние страницы без SDK и отключение loader через feature flag остаются на стороне клиента. Если вашему интерфейсу нужны собственные состояния загрузки, пустой выдачи и ошибки каталога, используйте Public API.

Типы для TypeScript​

Для подключения через <script> добавьте локальный файл деклараций в каталог, включённый в tsconfig.json. Он описывает поддерживаемые на этой странице методы и параметры; сам SDK по-прежнему загружается скриптом.

type ProductAvailabilityMap = Record<string, boolean>;

type ClientActions = {
  addProductToCartById?: (
    feedProductId: string,
    callback: (success: boolean) => void,
  ) => void;
  addProductToCart?: (
    vendorCode: string,
    callback: (success: boolean) => void,
  ) => void;
  resolveProductsAvailability?: (
    feedProductIds: string[],
    callback: (availability: ProductAvailabilityMap) => void,
  ) => void;
};

type ShopStoryShowOptions = {
  containerElement: Element;
  config: { clientId: string };
  actions?: ClientActions;
  cartUrl?: string;
};

type ShopStoryPlayerParams = {
  clientId: string;
  streamId: string;
};

declare global {
  interface Window {
    ShopStorySDK?: {
      show(options: ShopStoryShowOptions): void;
      showPlayer(params: ShopStoryPlayerParams): Promise<void>;
      refreshProductsAvailability?(): void;
    };
  }
}

export {};

Поле ShopStorySDK намеренно необязательное: до выполнения bundle объекта нет. По той же причине необязателен refreshProductsAvailability — вызывайте его только через проверку существования. Результат корзины и приоритет обработчиков описаны в разделе Добавление в корзину, карта наличия — в разделе Наличие и остатки.

SPA и lifecycle​

Текущий публичный контракт основного SDK рассчитан на один вызов show() для одного стабильного container. Публичного destroy() нет. В SPA сохраняйте container между route transitions и не вызывайте show() из каждого render/effect без собственной защиты от повторной инициализации.

PiP bundle читает согласованный PDP-шаблон и идентификатор товара во время своего lifecycle. До оценки SPA-интеграции передайте ShopStory используемый router, список PDP routes, способ смены SKU и момент замены DOM. Проверка должна охватывать прямой вход, client-side переход между товарами, back/forward и уход с PDP.

Что включить в оценку​

Если неизвестны SPA lifecycle, целевые браузеры или cart contract, оценка этих частей остаётся discovery scope. Базовый MPA-каталог с переходом на PDP можно оценивать отдельно.