Конфигурация и кастомизация Mobile SDK
В native iOS и Flutter на iOS задайте начальные параметры через configure(configuration:). На холодном запуске SDK может принять локальные настройки, пока серверная политика ещё загружается. В этом случае showProductVideo может вернуть ошибку runtimePolicyPending в результате запроса превью. При прямом открытии через open или openStream Swift возвращает .policyPending, Flutter — PlatformException с кодом runtime-policy-pending. Допуск к экрану и появление первого кадра проверяются отдельно. Диагностика политики
Параметры ShopStoryConfiguration
| Параметр | Тип и допустимые значения | Значение по умолчанию | Действие и сброс |
|---|---|---|---|
connection.applicationId | Обязательный непустой String, выданный ShopStory. SDK убирает пробелы по краям и приводит ID к нижнему регистру | Обязателен | Идентификатор проекта. Для смены вызовите configure с новым ID и настройками нового проекта |
connection.environment | Только Swift. У ShopStorySDKConnection.Environment одно значение .production | .production | Задаётся в configure. Flutter iOS использует production без отдельного поля |
connection.hostAppVersion | Необязательный String. Строка из пробелов считается отсутствующей | Отсутствует | Версия приложения магазина. Чтобы удалить значение, опустите его при следующем configure |
privacy.analytics | Bool в явной группе privacy | true для нового проекта без выбора | Разрешает аналитику ShopStory. Передавайте оба флага, для изменений используйте setPrivacy |
privacy.diagnostics | Bool в явной группе privacy | false для нового проекта без выбора | Разрешает отправку диагностических событий ShopStory. Задаётся независимо от аналитики |
appearance.primaryButtonColor | Необязательный String, непрозрачный #RRGGBB | Цвет разрешённой темы проекта, иначе чёрный фон и белый текст | Фон основного CTA, выбранных фильтров и кнопки открытия в товарном превью. Пустая группа возвращает наследование |
localization.locale | ShopStorySDKLocale / ShopStoryLocale. Значения приведены ниже | ru-RU | Язык и региональное форматирование SDK. Пустая группа восстанавливает ru-RU |
presentation.anchor | ShopStoryFloatingPlayerPosition / ShopStoryFloatingAnchor. Значения topLeading, topTrailing, bottomLeading, bottomTrailing | bottomTrailing при отсутствии настроек проекта | Угол окна. Пропущенное поле наследует значение следующего уровня |
presentation.horizontalMargin | Конечное неотрицательное число, Swift Double / Dart double. Максимум 96 pt / логических px | 16 при отсутствии настроек проекта | Расстояние от выбранного бокового края доступной области. Пропуск возвращает наследование |
presentation.verticalMargin | Конечное неотрицательное число, Swift Double / Dart double. Максимум 160 pt / логических px | Без настроек проекта 16 сверху, 24 снизу на PDP, 82 снизу на других экранах | Расстояние от выбранного верхнего или нижнего края доступной области. Пропуск возвращает наследование |
presentation.size | ShopStorySDKPresentationSize / ShopStoryPresentationSize. Значения standard, large | standard для типизированного размещения | Пресет медиаповерхности с учётом ориентации видео. Пропущенное поле на экране наследует значение приложения |
presentation.firstAppearance | В Swift у ShopStorySDKFirstAppearance два варианта — .immediate и .afterScroll(distance: 120). В Dart используйте ShopStoryFirstAppearance.immediate() или ShopStoryFirstAppearance.afterScroll(120). Расстояние конечное и неотрицательное | Немедленный показ | Первый показ превью или live-уведомления. Пропущенное поле экрана наследует значение приложения |
features.enabled | Bool | true при первом запуске без сохранённого запрета | Общий выключатель SDK. Пропуск сохраняет решение приложения. Для повторного допуска передайте true явно |
features.productVideo | Bool | true | Разрешает товарное превью. При false SDK убирает его и прекращает его lookup. Отдельное открытие эфира по streamId доступно при остальных разрешениях |
features.followMe | Bool | true | Разрешает продолжение просмотра в мини-плеере. При false окно скрывается и воспроизведение в нём приостанавливается с сохранением сессии. Уже открытый fullscreen продолжает работу |
features.manualMinimizeEnabled | Bool | true | Разрешает скрыть плавающее окно к краю и вернуть его. Стрелка Back полноэкранного плеера подчиняется правилам навигации |
features.liveNotification | Bool | false | Разрешает внутри приложения уведомление о текущем эфире на PDP и в каталоге. При отключении SDK прекращает lookup для уведомления |
minimizeOnPlayerBack | Bool, только Flutter iOS | false | При true стрелка Back SDK может свернуть незавершённый просмотр в Follow Me. Задаётся через configure |
Флаги функций действуют вместе с серверной политикой, допуском и видимостью экрана, состоянием сессии и запретами пользователя. Во Flutter Back из просмотра, открытого из активного встроенного списка, возвращает в этот список с выбранными фильтрами даже при minimizeOnPlayerBack: true. Подробнее о Back и переходах читайте в гайде по навигации.
Цвет, локаль и положение
primaryButtonColor применяется к фону основной кнопки встроенного плеера, выбранным фильтрам списка эфиров и круглой кнопке со стрелкой в нативной карточке товарного превью. Для локального цвета SDK подбирает чёрный или белый текст. Невыбранные фильтры сохраняют нейтральный стиль. После сброса SDK использует разрешённый цвет темы проекта, при его отсутствии — чёрный фон и белый текст. Остальные применимые токены темы проекта сохраняются. Форматы #RGB и цвета с альфа-каналом отклоняются.
Dynamic Type управляет размером системного текста списка и анонса. Проверьте переносы, фильтры и основные действия при увеличенном размере текста. Шрифт из темы проекта применяется к поддерживаемым товарным элементам. Публичная мобильная конфигурация содержит один токен оформления, primaryButtonColor. Управление шрифтом, системным масштабом текста и экраном магазина остаётся за приложением и платформой.
| Locale | Значение enum в Swift и Dart |
|---|---|
ru-RU | russianRussia |
ru-BY | russianBelarus |
be-BY | belarusianBelarus |
ru-KZ | russianKazakhstan |
kk-KZ | kazakhKazakhstan |
В Swift ShopStorySDKLocale(identifier:) принимает также короткие коды ru, be и kk, которые соответствуют ru-RU, be-BY и kk-KZ. В Dart выбирайте значение ShopStoryLocale. Белорусская и казахская локализации ещё требуют редакторской проверки. Перед выпуском проверьте тексты на нужных экранах. Если перевода строки нет, SDK покажет её по-русски.
Локаль задаёт тексты и форматы SDK. Рынок, ассортимент, цену, валюту и корзину задаёт приложение.
Native iOS
Вызовите configureShopStory один раз из объекта интеграции и передайте сохранённый приложением выбор privacy. Пример обновления меняет followMe, сохраняя остальные значения группы из настроек приложения.
import ShopStoryPlayerSDK
typealias ConfigurationCompletion = @MainActor (
Result<ShopStoryConfigurationApplication, ShopStoryConfigurationUpdateError>
) -> Void
@MainActor
func configureShopStory(
applicationId: String,
privacy: ShopStoryPrivacySettings
) throws {
try ShopStorySDK.shared.configure(configuration: ShopStoryConfiguration(
connection: .init(applicationId: applicationId),
privacy: privacy,
appearance: .init(primaryButtonColor: "#2456A6"),
localization: .init(locale: .russianRussia),
presentation: .init(anchor: .bottomLeading, size: .standard)
))
}
@MainActor
func updateFollowMe(
enabled: Bool,
current: ShopStorySDKFeatureUpdate,
completion: @escaping ConfigurationCompletion
) {
ShopStorySDK.shared.updateConfiguration(
update: .init(features: .init(
productVideo: current.productVideo,
followMe: enabled,
manualMinimizeEnabled: current.manualMinimizeEnabled,
liveNotification: current.liveNotification
)),
completion: completion
)
}
@MainActor
func resetVisualConfiguration(completion: @escaping ConfigurationCompletion) {
ShopStorySDK.shared.updateConfiguration(
update: .init(appearance: .init(), localization: .init(), presentation: .init()),
completion: completion
)
}
Flutter на iOS
Вызовите configureShopStory после проверки платформы и перед первым показом. Параметр privacy содержит два явных значения из настроек приложения.
import 'package:shopstory_player_flutter/shopstory_player_flutter.dart';
Future<void> configureShopStory(String applicationId, ShopStoryPrivacy privacy) {
return ShopStoryPlayerFlutter.instance.configure(
configuration: ShopStoryConfiguration(
connection: ShopStoryConnection(applicationId: applicationId),
privacy: privacy,
appearance: const ShopStoryAppearanceUpdate(primaryButtonColor: '#2456A6'),
localization: const ShopStoryLocalizationUpdate(locale: ShopStoryLocale.russianRussia),
presentation: const ShopStoryPresentationUpdate(
anchor: ShopStoryFloatingAnchor.bottomLeading,
size: ShopStoryPresentationSize.standard,
),
),
);
}
Future<ShopStoryConfigurationApplication> updateFollowMe(
bool enabled,
ShopStoryFeatureUpdate current,
) {
return ShopStoryPlayerFlutter.instance.updateConfiguration(
update: ShopStoryConfigurationUpdate(
features: ShopStoryFeatureUpdate(
productVideo: current.productVideo,
followMe: enabled,
manualMinimizeEnabled: current.manualMinimizeEnabled,
liveNotification: current.liveNotification,
),
),
);
}
Future<ShopStoryConfigurationApplication> resetVisualConfiguration() {
return ShopStoryPlayerFlutter.instance.updateConfiguration(
update: const ShopStoryConfigurationUpdate(
appearance: ShopStoryAppearanceUpdate(),
localization: ShopStoryLocalizationUpdate(),
presentation: ShopStoryPresentationUpdate(),
),
);
}
Чтобы запустить готовый пример Flutter, повторите команду из первого запуска с --target lib/customization.dart. Откройте превью через Show video и нажмите Back плеера. Пример задаёт ручной нижний отступ. При подключении ShopStoryAvoidArea уберите отступ, который резервировал место под ту же панель.
Правила обновления
Чтобы сменить цвет во время просмотра, передайте в updateConfiguration только группу appearance с новым primaryButtonColor. Чтобы сбросить лишь цвет, передайте только пустую appearance.
- Повторный
configure. Закрывает текущий плеер и делает прежние entrypoints недействительными. Заново задаёт цвет, локаль, placement и обычные флаги. Для той же конфигурации проекта сохраняется privacy-выбор, если группа опущена. Сохранённый общий запрет действует до явногоenabled: true. - Замена группы. В
updateConfigurationопущенная группа сохраняется. Переданная группа заменяется целиком. Внутри переданной группы пропущенные поля возвращаются к defaults или наследованию.features.enabledбез значения сохраняет прежнее решение. В примерах обновления этот флаг намеренно опущен. - Сброс. Пустая
appearanceвозвращает цвет проекта, пустаяlocalization—ru-RU, пустаяpresentationснимает настройки размещения приложения. Пустаяfeaturesвосстанавливает обычные флаги и сохраняет общий допуск. Для сброса одного поля передайте остальные нужные значения его группы. - Подтверждение. Для цвета и локали
appliedозначает подтверждение текущего документа.nextDocumentозначает, что локальные настройки готовы к следующему документу. Таймаут или потеря подтверждения оставляют принятое локальное значение для следующего документа. Для полного отключенияappliedподтверждает завершение очистки поверхностей SDK. - Ошибки. Неверный цвет, отрицательные значения,
NaNи бесконечность в placement отклоняют обновление целиком. Слишком большие конечные отступы ограничиваются указанными максимумами. Типы ошибок и действия при неудаче приведены в справочниках Swift и Flutter.
Расположение для отдельного экрана и показ после скролла
Передайте presentation вместе с фактически видимым экраном в setCurrentSurface. Отчёт заменяет override экрана. Если опустить presentation, override снимается даже при повторном отчёте о том же экране. Передавайте его каждый раз, пока он нужен. Угол и отступы наследуются в порядке «экран → настройки приложения → поддерживаемая геометрия проекта → значения SDK». Размер и момент первого показа наследуются от настроек приложения, затем применяются standard и immediate. Leading и trailing следуют направлению интерфейса.
Пресет standard задаёт медиаповерхность 112 × 190 для вертикального видео, 172 × 104 для горизонтального и 144 × 144 для квадратного. Единицы — pt на iOS и логические px во Flutter. large увеличивает медиаповерхность в 1,3 раза и при нехватке места может уменьшиться вплоть до standard. SDK учитывает также место для кнопок, safe area, клавиатуру и переданную приложением нижнюю панель.
Чтобы окно оставалось выше нижней навигации или панели корзины, передайте эту область через Flutter scope либо UIKit helper. При ручном размещении задайте позицию и отступы от safe area в логических единицах или запретите показ через allowed: false.
На схеме клавиатура закрыта. Во Flutter ShopStoryAvoidArea резервирует место под нижнюю панель и оставляет над ней ещё 12 логических пикселей. В UIKit avoidBottomBar(_:in:) поднимает границу доступной области до верхней кромки панели. На обеих платформах SDK применяет horizontalMargin и verticalMargin в оставшейся области.
Четыре точки в углах области отмечают позиции topLeading, topTrailing, bottomLeading и bottomTrailing. На схеме выбран bottomTrailing при LTR. При RTL leading и trailing меняются местами.
Клавиатура, перекрывающая нижнюю часть окна приложения, уменьшает доступную высоту. Если окно стандартного размера вместе с кнопками не помещается, SDK скрывает его. Follow Me при этом приостанавливает воспроизведение и сохраняет сессию. На iOS область нажатия каждой кнопки составляет минимум 44 × 44 pt.
Для отложенного preview задайте firstAppearance: .afterScroll(distance: 120) в Swift или firstAppearance: ShopStoryFirstAppearance.afterScroll(120) в Dart. Передавайте абсолютную позицию основного скролл-контейнера. afterScroll(0) эквивалентен immediate. При положительном пороге первый показ ждёт отчёта с достаточной позицией. Возврат к началу списка после показа окно не скрывает.
- Swift. Сообщите surface, вызовите
showProductVideoдля текущего товара и передавайте абсолютную позицию в callback, полученный изplayer.scrollOffsetReporter(for: feedProductId). Для уже восстановленной позиции используйтеrestoredScrollOffsetпри показе preview. - Dart. После
setCurrentSurfaceи запроса preview для текущего товара получитеawait sdk.captureScrollOffsetReporter(). Передайте ему текущее смещение и последующие значения из вашегоScrollController.
При новом товаре или маршруте получите новый callback и отвяжите listener предыдущего экрана. Старые отчёты игнорируются. Порог первого появления действует для preview и опционального live-уведомления. Follow Me продолжает подчиняться карте видимых поверхностей.
Для отслеживания прокрутки текущей PDP используйте observeScrollView в UIKit либо scrollController и autoReportScroll во Flutter. Сигнатуры и условия подключения описаны в iOS reference и Flutter reference.
Для уведомления включите liveNotification: true и сообщите разрешённый catalog или productDetail. Это уведомление внутри приложения. Нажатие открывает текущий эфир в fullscreen. Во время активного просмотра или товарного превью уведомление уступает им место. При отсутствии подходящего эфира оно скрыто.
Если в каталоге настроен afterScroll, сообщите catalog, получите sdk.player.scrollOffsetReporter() без аргумента в Swift или await sdk.captureScrollOffsetReporter() в Dart. Передавайте начальную и последующие абсолютные позиции каталога. Для явной повторной проверки используйте sdk.player.refreshLiveNotification() или await sdk.refreshLiveNotification() на актуальном экране.
Privacy и отключение
Сохраните выбор пользователя в приложении и передайте оба флага в configure до открытия плеера. Если сбор должен дождаться согласия, начните с analytics: false, diagnostics: false. Commerce требует оба явных значения даже при совпадении с defaults. При смене проекта передайте актуальный выбор для нового проекта.
Чтобы обновить согласие, вызовите sdk.player.setPrivacy(settings:completion:) в Swift или await sdk.setPrivacy(ShopStoryPrivacy(...)) во Flutter. Проверьте подтверждение. SDK продолжает функциональные запросы за политикой, видео и содержимым эфира. Локальные callbacks остаются доступны, их дальнейшую отправку контролирует приложение. Уже отправленные запросы отозвать нельзя. Область действия аналитики
Чтобы остановить работу SDK, передайте features.enabled: false вместе с остальными нужными флагами группы и дождитесь applied. Уже отправленная операция корзины сохраняет исходного владельца. Запрет действует и при ошибке очистки. Если очистке мешает модальное окно приложения, закройте его и повторите отключение.
Чтобы снова разрешить показ, передайте enabled: true с остальными нужными флагами. Плеер можно открыть, когда это разрешают политика SDK и текущий экран.
Проверка для выпуска — смена темы в открытом player, фильтр в списке, reset, узкий экран с клавиатурой, отзыв согласия, выключение и повторное включение. Диагностика · Lifecycle и выпуск