<!-- Canonical: https://docs.shopstory.live/docs/guide/mobile-sdk-configuration -->

# Конфигурация и кастомизация Mobile SDK

В native iOS и Flutter на iOS задайте начальные параметры через `configure(configuration:)`. На холодном запуске SDK может принять локальные настройки, пока серверная политика ещё загружается. В этом случае `showProductVideo` может вернуть ошибку `runtimePolicyPending` в результате запроса превью. При прямом открытии через `open` или `openStream` Swift возвращает `.policyPending`, Flutter — `PlatformException` с кодом `runtime-policy-pending`. Допуск к экрану и появление первого кадра проверяются отдельно. [Диагностика политики](<https://docs.shopstory.live/docs/operations/troubleshooting#mobile>)

## Параметры `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 и переходах читайте в [гайде по навигации](<https://docs.shopstory.live/docs/guide/mobile-sdk-navigation>).

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

`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`, сохраняя остальные значения группы из настроек приложения.

ShopStorySettings.swift

```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

```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, повторите команду из [первого запуска](<https://docs.shopstory.live/docs/guide/mobile-sdk-flutter#%D0%BF%D0%B5%D1%80%D0%B2%D0%BE%D0%B5-%D0%B2%D0%B8%D0%B4%D0%B5%D0%BE-%D0%B8%D0%B7-%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D0%B0>) с `--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](<https://docs.shopstory.live/docs/reference/mobile-sdk-ios#%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8>) и [Flutter](<https://docs.shopstory.live/docs/reference/mobile-sdk-flutter#%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8>).

## Расположение для отдельного экрана и показ после скролла

Передайте `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](<https://docs.shopstory.live/docs/guide/mobile-sdk-flutter#%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B8%D1%82%D0%B5-%D0%BF%D1%80%D0%B5%D0%B2%D1%8C%D1%8E-%D0%B8-%D0%BD%D0%B8%D0%B6%D0%BD%D1%8E%D1%8E-%D0%BF%D0%B0%D0%BD%D0%B5%D0%BB%D1%8C>) либо [UIKit helper](<https://docs.shopstory.live/docs/guide/mobile-sdk-ios#%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA%D0%B8-pdp-%D0%B4%D0%BB%D1%8F-uikit-%D0%B8-swiftui>). При ручном размещении задайте позицию и отступы от safe area в логических единицах или запретите показ через `allowed: false`.

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

На схеме клавиатура закрыта. Во 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](<https://docs.shopstory.live/docs/reference/mobile-sdk-ios#%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA%D0%B8-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8>) и [Flutter reference](<https://docs.shopstory.live/docs/reference/mobile-sdk-flutter#%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA%D0%B8-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8>).

Для уведомления включите `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 остаются доступны, их дальнейшую отправку контролирует приложение. Уже отправленные запросы отозвать нельзя. [Область действия аналитики](<https://docs.shopstory.live/docs/guide/analytics-mobile#consent-%D0%B8-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%B5>)

Чтобы остановить работу SDK, передайте `features.enabled: false` вместе с остальными нужными флагами группы и дождитесь `applied`. Уже отправленная операция корзины сохраняет исходного владельца. Запрет действует и при ошибке очистки. Если очистке мешает модальное окно приложения, закройте его и повторите отключение.

Чтобы снова разрешить показ, передайте `enabled: true` с остальными нужными флагами. Плеер можно открыть, когда это разрешают политика SDK и текущий экран.

Проверка для выпуска — смена темы в открытом player, фильтр в списке, reset, узкий экран с клавиатурой, отзыв согласия, выключение и повторное включение. [Диагностика](<https://docs.shopstory.live/docs/operations/troubleshooting#mobile>) · [Lifecycle и выпуск](<https://docs.shopstory.live/docs/guide/mobile-sdk-releases#%D0%BF%D1%80%D0%B8%D1%91%D0%BC%D0%BA%D0%B0-%D0%BF%D0%B5%D1%80%D0%B5%D0%B4-%D0%B2%D1%8B%D0%BF%D1%83%D1%81%D0%BA%D0%BE%D0%BC>)
