Перейти к основному содержимому

Конфигурация и кастомизация 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.analyticsBool в явной группе privacytrue для нового проекта без выбораРазрешает аналитику ShopStory. Передавайте оба флага, для изменений используйте setPrivacy
privacy.diagnosticsBool в явной группе privacyfalse для нового проекта без выбораРазрешает отправку диагностических событий ShopStory. Задаётся независимо от аналитики
appearance.primaryButtonColorНеобязательный String, непрозрачный #RRGGBBЦвет разрешённой темы проекта, иначе чёрный фон и белый текстФон основного CTA, выбранных фильтров и кнопки открытия в товарном превью. Пустая группа возвращает наследование
localization.localeShopStorySDKLocale / ShopStoryLocale. Значения приведены нижеru-RUЯзык и региональное форматирование SDK. Пустая группа восстанавливает ru-RU
presentation.anchorShopStoryFloatingPlayerPosition / ShopStoryFloatingAnchor. Значения topLeading, topTrailing, bottomLeading, bottomTrailingbottomTrailing при отсутствии настроек проектаУгол окна. Пропущенное поле наследует значение следующего уровня
presentation.horizontalMarginКонечное неотрицательное число, Swift Double / Dart double. Максимум 96 pt / логических px16 при отсутствии настроек проектаРасстояние от выбранного бокового края доступной области. Пропуск возвращает наследование
presentation.verticalMarginКонечное неотрицательное число, Swift Double / Dart double. Максимум 160 pt / логических pxБез настроек проекта 16 сверху, 24 снизу на PDP, 82 снизу на других экранахРасстояние от выбранного верхнего или нижнего края доступной области. Пропуск возвращает наследование
presentation.sizeShopStorySDKPresentationSize / ShopStoryPresentationSize. Значения standard, largestandard для типизированного размещенияПресет медиаповерхности с учётом ориентации видео. Пропущенное поле на экране наследует значение приложения
presentation.firstAppearanceВ Swift у ShopStorySDKFirstAppearance два варианта — .immediate и .afterScroll(distance: 120). В Dart используйте ShopStoryFirstAppearance.immediate() или ShopStoryFirstAppearance.afterScroll(120). Расстояние конечное и неотрицательноеНемедленный показПервый показ превью или live-уведомления. Пропущенное поле экрана наследует значение приложения
features.enabledBooltrue при первом запуске без сохранённого запретаОбщий выключатель SDK. Пропуск сохраняет решение приложения. Для повторного допуска передайте true явно
features.productVideoBooltrueРазрешает товарное превью. При false SDK убирает его и прекращает его lookup. Отдельное открытие эфира по streamId доступно при остальных разрешениях
features.followMeBooltrueРазрешает продолжение просмотра в мини-плеере. При false окно скрывается и воспроизведение в нём приостанавливается с сохранением сессии. Уже открытый fullscreen продолжает работу
features.manualMinimizeEnabledBooltrueРазрешает скрыть плавающее окно к краю и вернуть его. Стрелка Back полноэкранного плеера подчиняется правилам навигации
features.liveNotificationBoolfalseРазрешает внутри приложения уведомление о текущем эфире на PDP и в каталоге. При отключении SDK прекращает lookup для уведомления
minimizeOnPlayerBackBool, только Flutter iOSfalseПри true стрелка Back SDK может свернуть незавершённый просмотр в Follow Me. Задаётся через configure

Флаги функций действуют вместе с серверной политикой, допуском и видимостью экрана, состоянием сессии и запретами пользователя. Во Flutter Back из просмотра, открытого из активного встроенного списка, возвращает в этот список с выбранными фильтрами даже при minimizeOnPlayerBack: true. Подробнее о Back и переходах читайте в гайде по навигации.

Цвет, локаль и положение​

primaryButtonColor применяется к фону основной кнопки встроенного плеера, выбранным фильтрам списка эфиров и круглой кнопке со стрелкой в нативной карточке товарного превью. Для локального цвета SDK подбирает чёрный или белый текст. Невыбранные фильтры сохраняют нейтральный стиль. После сброса SDK использует разрешённый цвет темы проекта, при его отсутствии — чёрный фон и белый текст. Остальные применимые токены темы проекта сохраняются. Форматы #RGB и цвета с альфа-каналом отклоняются.

Dynamic Type управляет размером системного текста списка и анонса. Проверьте переносы, фильтры и основные действия при увеличенном размере текста. Шрифт из темы проекта применяется к поддерживаемым товарным элементам. Публичная мобильная конфигурация содержит один токен оформления, primaryButtonColor. Управление шрифтом, системным масштабом текста и экраном магазина остаётся за приложением и платформой.

LocaleЗначение enum в Swift и Dart
ru-RUrussianRussia
ru-BYrussianBelarus
be-BYbelarusianBelarus
ru-KZrussianKazakhstan
kk-KZkazakhKazakhstan

В Swift ShopStorySDKLocale(identifier:) принимает также короткие коды ru, be и kk, которые соответствуют ru-RU, be-BY и kk-KZ. В Dart выбирайте значение ShopStoryLocale. Белорусская и казахская локализации ещё требуют редакторской проверки. Перед выпуском проверьте тексты на нужных экранах. Если перевода строки нет, SDK покажет её по-русски.

Локаль задаёт тексты и форматы SDK. Рынок, ассортимент, цену, валюту и корзину задаёт приложение.

Native iOS​

Вызовите configureShopStory один раз из объекта интеграции и передайте сохранённый приложением выбор privacy. Пример обновления меняет followMe, сохраняя остальные значения группы из настроек приложения.

ShopStorySettings.swift
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 содержит два явных значения из настроек приложения.

shopstory_settings.dart
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.

Границы мини-плеера на PDP

На схеме клавиатура закрыта. Во Flutter ShopStoryAvoidArea резервирует место под нижнюю панель и оставляет над ней ещё 12 логических пикселей. В UIKit avoidBottomBar(_:in:) поднимает границу доступной области до верхней кромки панели. На обеих платформах SDK применяет horizontalMargin и verticalMargin в оставшейся области.

Размещение окна в нижнем углу PDPКлавиатура закрыта. Окно в bottomTrailing для LTR, выше нижней панели. Полоса между доступной областью и панелью показывает дополнительный зазор Flutter.Safe AreaДоступная областьFollow MehorizontalMarginverticalMarginFlutter · зазор 12 лог. pxНижняя панель приложенияНижняя навигация или кнопка «В корзину»

Четыре точки в углах области отмечают позиции 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 и выпуск