<!-- Canonical: https://docs.shopstory.live/docs/guide/integration-methods -->

# Методы интеграции

До установки команда 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 не означает, что этот виджет уже включён.

Подготовку выгрузки описывает раздел [Товарный фид](<https://docs.shopstory.live/docs/guide/feed-requirements>), чтение товаров через API — [Интеграция с интернет-магазином](<https://docs.shopstory.live/docs/guide/custom-commerce-integrations>). После этого подключите [Web SDK](<https://docs.shopstory.live/docs/guide/web-sdk>) и нужное [действие корзины](<https://docs.shopstory.live/docs/guide/add-to-cart>).

## Public API

Public API подходит, когда клиент строит собственный список эфиров и записей или сам управляет состояниями интерфейса.

Клиентская команда отвечает за:

- HTTP-клиент и тайм-ауты;
- проверку транспортного кода и JSON-конверта;
- состояния загрузки, пустой выдачи и ошибки;
- собственный UI, аналитику и доступность;
- корректную работу при временной недоступности ShopStory.

API можно вызывать с сервера клиента. Запрос из браузера возможен после регистрации точного origin в ShopStory. `applicationId` передаётся в запросе как идентификатор проекта и не считается секретом.

Первый запрос описан в [Quickstart](<https://docs.shopstory.live/docs/guide/quickstart>). Форматы и методы собраны в разделах [Формат ответов](<https://docs.shopstory.live/docs/guide/architecture>), [Каталог эфиров](<https://docs.shopstory.live/docs/guide/catalog-streams>) и [Mini-player API](<https://docs.shopstory.live/docs/guide/mini-player>).

## Mobile SDK

Mobile SDK встраивает live, записи и product video в нативное приложение ритейлера. SDK управляет воспроизведением и media lifecycle. PDP, навигация, авторизация, корзина и результат покупки остаются в приложении.

Нативный API SDK управляет встроенным WebView-плеером. Приложение предоставляет свои экраны и контейнеры; создавать собственный WebView или bridge не требуется. Архитектура и доступность iOS, Flutter и Android: [SDK и WebView](<https://docs.shopstory.live/docs/guide/mobile-sdk#sdk-and-webview>), [платформенная поставка](<https://docs.shopstory.live/docs/guide/mobile-sdk#%D0%BF%D0%BB%D0%B0%D1%82%D1%84%D0%BE%D1%80%D0%BC%D0%B5%D0%BD%D0%BD%D0%B0%D1%8F-%D0%BF%D0%BE%D1%81%D1%82%D0%B0%D0%B2%D0%BA%D0%B0>).

Клиентская команда:

- передаёт тот же строковый `feedProductId`, что используется в выбранном источнике товарных данных;
- встраивает SDK в существующий native navigation и lifecycle;
- обрабатывает типизированное действие с товаром через свой router или cart-команду;
- подтверждает успех корзины только по ответу своей commerce-системы;
- выпускает и при необходимости откатывает согласованную версию пакета.

В integration handoff ShopStory указывает доступ к пакету, точную совместимую версию, `applicationId`, тестовые товары и checklist для этой версии. Доступ к пакету, клиентские routes и параметры rollout публично не размещаются.

Для mobile-интеграции используйте [Mobile SDK](<https://docs.shopstory.live/docs/guide/mobile-sdk>). Формат выгрузки описан в [товарном фиде](<https://docs.shopstory.live/docs/guide/feed-requirements>), товарный API и варианты — в [интеграции с интернет-магазином](<https://docs.shopstory.live/docs/guide/custom-commerce-integrations>). Для прямой корзины дополнительно используйте [контракт добавления товара](<https://docs.shopstory.live/docs/guide/add-to-cart>).

## Commerce-интеграции

Покупательское действие подключается следующими способами:

1. Открытие карточки товара — базовый сценарий: на web через URL, в Mobile SDK через нативный route по `feedProductId`.
2. Добавление в корзину без перехода: на web используется callback клиента, в Mobile SDK — типизированное действие host app.
3. Показ наличия по выбранному магазину до клика — штатный [обработчик наличия](<https://docs.shopstory.live/docs/guide/product-availability>) Web SDK.
4. Товарные данные через API, выбор SKU в плеере, персональная цена и формы получения подключаются через расширенный commerce-контракт.

Commerce-система клиента определяет применимые магазин и способ доставки, проверяет цену и остаток и подтверждает результат добавления в корзину. ShopStory не рассчитывает эти значения. Расширенный контракт описывает отображение условий магазина и работу с вариантами; штатный обработчик наличия цену не меняет.

Для расширенного сценария получите [комплект подключения SDK](<https://docs.shopstory.live/docs/guide/custom-commerce-integrations#commerce-sdk-delivery>) с версией, регистрацией обработчиков и запускаемым примером. Подробные контракты: [Добавление в корзину](<https://docs.shopstory.live/docs/guide/add-to-cart>), [Наличие и остатки](<https://docs.shopstory.live/docs/guide/product-availability>) и [Интеграция с интернет-магазином](<https://docs.shopstory.live/docs/guide/custom-commerce-integrations>).

## Матрица решения

| Требование | 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 принимает другой внутренний ключ, преобразуйте его один раз на границе системы ритейлера.