# Вопросы интеграторов Для последовательной проверки по симптому используйте [диагностику интеграции](). Определения показателей и сверка двух отчётов: [события и метрики](). ## Доступ и конфигурация ### Как начать интеграцию? Передайте команде 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.