Вопросы интеграторов

Для последовательной проверки по симптому используйте диагностику интеграции. Определения показателей и сверка двух отчётов: события и метрики.

Доступ и конфигурация​

Как начать интеграцию?​

Передайте команде ShopStory источник товарных данных — фид или API магазина, единый 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-домены не перепутаны.

Контент и товары​

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

Стандартный полный плеер открывается поверх страницы: как модальное окно на desktop и на весь экран на mobile. Внутри блока страницы show() размещает каталог. Для полного inline-плеера или собственного модального окна заранее согласуйте отдельный способ монтажа; showPlayer() не принимает контейнер. Сравнение вариантов: размещение Web SDK.

Что означает no_active_stream?​

Для указанного товара нет подходящего опубликованного live или записи либо ID на странице не совпадает с feedProductId из конфигурации проекта. Это штатное пустое состояние, а не сбой сервиса. Проверьте связку в Mini-player API.

Почему API возвращает active, а mini-player на PDP не появляется?​

Ответ подтверждает наличие видео для товара и предоставляет поддерживаемый body.stream.playerUrl как непрозрачный URL плеера. Появление виджета зависит от настройки ShopStory под конкретный PDP-шаблон: нужно определить товарный ID, место вставки и исключённые страницы. Передайте URL проблемной карточки и название шаблона.

Насколько свежие данные о товаре и доступности?​

В режиме фида каталог, названия, изображения и цены берутся из последней успешно обработанной выгрузки; частота синхронизации согласуется для проекта. Товарный API возвращает описание и актуальные условия через обработчик магазина: Интеграция с интернет-магазином. При сочетании источников фид передаёт описание, а API — условия покупателя. Штатный обработчик наличия Web SDK запрашивает остаток выбранного магазина при открытии эфира и при смене магазина. Окончательное подтверждение остаётся за cart-командой ритейлера: Наличие товара и остатки.

Фид нужно обновлять каждые четыре часа?​

Интервал зависит от роли фида и допустимого возраста его данных. Если мастер-фид передаёт каталог/SKU, а расширенный commerce API — актуальные условия покупателя, частоту выбирают по изменениям каталога. Персональные цены и остатки сами по себе не требуют нового импорта. В стандартном режиме цена берётся из фида. Boolean-обработчик не меняет цену и не снимает установленный фидом запрет покупки. Правило выбора и проверка свежести: частота обновления фида.

Как подключить разные страны и валюты?​

Согласуйте по каждому рынку каталог, валюту и назначенную конфигурацию проекта/applicationId. Геопозиция зрителя не переключает фид автоматически. Проверяйте сохранение валюты и дробной цены в карточке, кабинете и отчётах; денежные итоги разных валют не складываются без отдельного правила конвертации. Подробнее: страны и валюты.

Какой идентификатор товара использовать?​

Используйте один строковый feedProductId в товарных данных, на web- и native-PDP и в product action. Сохраняйте ведущие нули и регистр. Если commerce API принимает другой внутренний SKU, преобразуйте идентификатор на границе системы ритейлера, а не вводите второй ID для ShopStory.

Можно проверять остаток через API ритейлера перед покупкой?​

Да. Web SDK передаёт список товаров эфира в обработчик наличия на сайте ритейлера, тот обращается к своему stock API с выбранным магазином и возвращает карту наличия. SDK обновляет карточки до клика по кнопке. Запрос выполняется кодом сайта с его сессией, поэтому открывать stock API для ShopStory не нужно.

Если stock API недоступен из браузера покупателя, используйте серверного посредника магазина. Персональные цены и выбор SKU подключаются через расширенный commerce-контракт. Boolean-контракт наличия, тайм-ауты и приоритет источников: Наличие товара и остатки.

Можно передавать товары через API и выбирать цвет или размер в плеере?​

Это отдельная проектная commerce-интеграция. До оценки разработки подтвердите с ShopStory версию SDK, целевые платформы и способ регистрации обработчиков; параметры стандартного show() не включают эти возможности автоматически.

В согласованной поставке источником товаров и вариантов может быть фид или API магазина. Опции соответствуют реальным SKU, а магазин возвращает актуальные условия и подтверждает добавление выбранного варианта. Контракт и prerequisites: Интеграция с интернет-магазином.

Где регистрировать getProductConditions и startCommerceAction?​

В commerce v1 обработчики регистрируются до открытия плеера: на Web — через ShopStorySDK.registerCommerceAdapter, на native и Flutter — через API соответствующего пакета. Порядок регистрации и Web-фрагмент описаны в commerce-руководстве. Перед подключением получите совместимые версии и полный пример. Эти обработчики не являются HTTP endpoints Public API.

Мы обязаны подключать проверку остатков?​

В стандартном Web-подключении обработчик наличия необязателен: без него используется снимок фида. Его подключают, когда наличие зависит от выбранного магазина или меняется чаще, чем синхронизируется фид. В расширенном commerce v1 актуальные условия, включая наличие, возвращает getProductConditions; это отдельный контракт.

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 SDK — это библиотека или WebView?​

SDK — библиотека с нативным API; внутри неё полный плеер работает в управляемом WebView. SDK отвечает за media lifecycle и bridge, приложение — за свои экраны, навигацию, авторизацию и корзину. Собирать собственный WebView-плеер не требуется. Объяснение и схема архитектуры.

Какие mobile-платформы входят в текущий маршрут?​

Опубликованные инструкции и starters относятся к указанным в них версиям native iOS и Flutter на iOS. Для выбранной платформы ShopStory передаёт точную версию SDK, совместимый Web runtime и, при использовании Flutter, adapter/native пакеты. Требования к toolchain фиксируются в integration handoff.

Android SDK и Flutter на Android согласуются отдельно. Платформенная поставка помогает выбрать маршрут, а Android-контракт задаёт состав пакета, карту переходов и приёмку. Flutter на iOS не подтверждает поддержку Android.

Как подключить Mobile SDK?​

Начните с руководства Mobile SDK. Оно описывает пользовательский сценарий, единый feedProductId, границу ответственности, product actions, lifecycle, безопасность и приёмку.

Для опубликованных поставок native iOS и Flutter на iOS скачайте starter и проверьте пару версий. Для Android получите пакет и пример своей версии. Доступы и тестовые товары выдаёт ShopStory. Расширенный commerce подключается отдельно по контракту поставки.

Где проходит граница white-label?​

SDK работает внутри приложения ритейлера: каталог, PDP, навигация, авторизация, корзина и native analytics остаются частью приложения. Визуальная конфигурация web-плеера согласуется для проекта. Изменение элементов, которых нет в поставленной документации, не входит в публичный контракт и фиксируется отдельно до приёмки.

Что проверить для чата перед выпуском в App Store или Google Play?​

Включите в приёмку правила, фильтрацию сообщений, жалобы, персональную блокировку и действия модератора. Зафиксируйте, кто обрабатывает обращения. Проверяются механизмы конкретной поставки и итоговая сборка приложения; одно наличие правил чата не подтверждает готовность. Ответственность описана в разделе модерации чата; проверяемые результаты — в матрице готовности.

Поддержка​

Что приложить к техническому обращению?​

• URL страницы и applicationId;
• время запроса с часовым поясом;
• браузер, ОС или mobile-платформу;
• endpoint и безопасный фрагмент запроса и ответа;
• шаги воспроизведения и ожидаемый результат.

Не отправляйте пароли, cookies, access tokens и персональные данные. Канал: support@shopstory.live. Порядок реакции и SLA определяются договором проекта.

Аналитика​

Почему в ShopStory и счётчике магазина разные числа?​

Buy intent фиксирует клик, а E-commerce add — подтверждённое добавление. Переход на PDP, заказ и оплата измеряются отдельно. Сверяйте также период, consent и покрытие страниц: смысл метрик.

Достаточно включить E-commerce в Яндекс Метрике?​

Нет. Нужны согласованный data container и подтверждённая отправка из SDK для проекта. Проверяются событие в container, запрос аналитики и отчёт: Web tracking.

Можно перенести старую AppMetrica-инструкцию в Mobile SDK?​

Принцип отправки после успеха Cart API сохраняется. Старый WebView bridge и классы YMM не являются текущим host contract: используйте mobile tracking и API установленной AppMetrica.