Вопросы интеграторов
Доступ и конфигурация
Как начать интеграцию?
Передайте команде ShopStory ссылку на товарный фид, единый feedProductId, целевые страницы и нужное поведение кнопки «Купить». Для web-интеграции добавьте production- и test-домены. ShopStory подготовит applicationId, зарегистрирует нужные origins и настроит компоненты. Затем выберите Web SDK, Public API или Mobile SDK.
applicationId нужно хранить как секрет?
Нет. Это идентификатор проекта, который виден в браузерных запросах и выбирает нужную конфигурацию. Он не заменяет авторизацию и не должен давать доступ к заказам, профилю, корзине или другим чувствительным операциям. Пароли, session cookies и реальные access tokens остаются секретами.
Почему запрос работает из терминала, но не из браузера?
Для браузерного доступа ShopStory регистрирует точный origin клиента. Сверьте протокол, hostname и порт страницы с переданными при подключении значениями. Не обходите проблему открытым CORS relay. Подробнее: Quickstart.
Почему Web SDK загрузился, но показал пустую или неверную конфигурацию?
Для основного SDK проверьте config.clientId в вызове show(). PiP bundle использует конфигурацию зарегистрированного hostname. В обоих случаях передайте текущий URL и applicationId менеджеру интеграции и проверьте, что test- и production-домены не перепутаны.
Контент и товары
Что означает no_active_stream?
Для указанного товара нет подходящего опубликованного live или записи либо ID на странице не совпадает с feedProductId из принятого фида. Это штатное пустое состояние, а не сбой сервиса. Проверьте связку в Mini-player API.
Почему API возвращает active, а mini-player на PDP не появляется?
Ответ подтверждает наличие видео для товара и предоставляет поддерживаемый body.stream.playerUrl как непрозрачный URL плеера. Появление виджета зависит от настройки ShopStory под конкретный PDP-шаблон: нужно определить товарный ID, место вставки и исключённые страницы. Передайте URL проблемной карточки и название шаблона.
Насколько свежие данные о товаре и доступности?
Каталог, названия, изображения и цены берутся из последней успешно обработанной версии товарного фида; частота синхронизации согласуется для проекта. Наличие может быть свежее каталога: если для проекта настроен обработчик наличия, Web SDK запрашивает остаток выбранного магазина при открытии эфира и при смене магазина. Окончательное подтверждение остаётся за cart-командой ритейлера: Наличие товара и остатки.
Какой идентификатор товара использовать?
Используйте один строковый feedProductId в товарном фиде, на web- и native-PDP и в product action. Сохраняйте ведущие нули и регистр. Если commerce API принимает другой внутренний SKU, преобразуйте идентификатор на границе системы ритейлера, а не вводите второй ID для ShopStory.
Можно проверять остаток через API ритейлера перед покупкой?
Да. Web SDK передаёт список товаров эфира в обработчик наличия на сайте ритейлера, тот обращается к своему stock API с выбранным магазином и возвращает карту наличия. SDK обновляет карточки до клика по кнопке. Запрос выполняется кодом сайта с его сессией, поэтому открывать stock API для ShopStory не нужно.
Индивидуальная доработка нужна только там, где этой границы недостаточно: например, если stock API недоступен из браузера покупателя и требует серверного посредника. Контракт, тайм-ауты и приоритет источников: Наличие товара и остатки.
Мы обязаны подключать проверку остатков?
Нет. Без обработчика наличие берётся из фида, и SDK ничего не вызывает. Обработчик подключается, когда наличие зависит от выбранного магазина или меняется чаще, чем синхронизируется фид.
API
Почему /v2/ использует application=, а /v3/ — applicationId=?
У разных семейств endpoint исторически разные имена query-параметра. Используйте параметр из схемы конкретного endpoint и не меняйте версию URL механически. Подробнее: Формат запросов и ответов.
Как обрабатывать HTTP 200 с status: 400 внутри JSON?
Проверяйте оба уровня независимо. Сначала обработайте HTTP-код или сетевую ошибку, затем верхнеуровневый status и после него состояние внутри body, если оно есть. HTTP 200 сам по себе не подтверждает успех операции.
Можно ли полагаться на поля, которых нет в OpenAPI?
Нет. Клиент должен игнорировать незнакомые необязательные поля и использовать документированную схему. Случайно присутствующее поле может быть внутренним или нестабильным.
Как тестировать без активного live?
Используйте опубликованную запись, переданную ShopStory для приёмки. Для live-состояния нужна отдельная сессия тестового эфира; статичный mock не подтверждает поведение в реальном времени.
Mobile
Какие mobile-платформы входят в текущий маршрут?
Сейчас доступны native iOS и Flutter-приложение на iOS. Для native iOS ShopStory передаёт точную версию SDK, для Flutter — совместимую пару Flutter/native пакетов. Требования к toolchain фиксируются в integration handoff. Для другого mobile stack сначала согласуются runtime, объём работ и приёмка; web-инструкция не считается готовой mobile-поставкой.
Как подключить Mobile SDK?
Начните с руководства Mobile SDK. Оно описывает пользовательский сценарий, единый feedProductId, границу ответственности, product actions, lifecycle, безопасность и приёмку.
Доступ к пакету, точную совместимую версию, host contract, тестовые товары, rollout и rollback ShopStory передаёт назначенной команде в integration handoff. Web SDK нельзя использовать как native mobile-инструкцию.
Где проходит граница white-label?
SDK работает внутри приложения ритейлера: каталог, PDP, навигация, авторизация, корзина и native analytics остаются частью приложения. Визуальная конфигурация web-плеера согласуется для проекта. Изменение элементов, которых нет в поставленной документации, не входит в публичный контракт и фиксируется отдельно до приёмки.
Поддержка
Что приложить к техническому обращению?
- URL страницы и
applicationId; - время запроса с часовым поясом;
- браузер, ОС или mobile-платформу;
- endpoint и безопасный фрагмент запроса и ответа;
- шаги воспроизведения и ожидаемый результат.
Не отправляйте пароли, cookies, access tokens и персональные данные. Канал: support@shopstory.live. Порядок реакции и SLA определяются договором проекта.