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

# Навигация, список эфиров и Follow Me

После [первого запуска на iOS](<https://docs.shopstory.live/docs/guide/mobile-sdk-ios>) или [Flutter на iOS](<https://docs.shopstory.live/docs/guide/mobile-sdk-flutter>) подключите SDK к роутеру магазина. Выберите точку входа по задаче пользователя.

| Задача | Native iOS | Flutter на iOS |
| --- | --- | --- |
| Постоянный раздел «Эфиры» в вашем меню или таббаре | `sdk.player.makeStreamListView()` | `ShopStoryStreamList(active: ...)` |
| Отдельное модальное окно со списком | `sdk.player.openStreamList(from:completion:)` | `sdk.openStreamList()` |
| Открыть конкретный эфир или запись через баннер либо ссылку | `sdk.player.openStream(streamId:from:completion:)` | `sdk.openStream(streamId: ...)` |
| Показать товарное превью или связанный live на PDP | `sdk.player.showProductVideo(feedProductId:from:completion:)` | `ShopStoryProductDetailScope` или `sdk.showProductVideo(feedProductId: ...)` |

`showProductVideo` запрашивает и показывает видео на карточке. Полный плеер открывается по нажатию на товарное превью или окно прямого эфира. [Как открыть товарный эпизод из своего интерфейса](<https://docs.shopstory.live/docs/guide/mobile-sdk-navigation#%D0%BE%D1%82%D0%BA%D1%80%D0%BE%D0%B9%D1%82%D0%B5-%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D0%BD%D1%8B%D0%B9-%D1%8D%D0%BF%D0%B8%D0%B7%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%81%D0%B8>)

## Сообщите фактически видимый экран

Роутер приложения сообщает текущую `ShopStorySurface` и разрешение `allowed` после первого появления экрана, push, Back, смены вкладки или закрытия модального окна. Сообщайте верхний видимый экран активной вкладки. Скрытая вкладка и размонтированный экран не должны отправлять собственное состояние. Неизвестный экран сообщайте как `.unknown` / `ShopStorySurface.unknown` с `allowed: false`.

| Экран приложения | Surface | Что сообщить |
| --- | --- | --- |
| Главная, каталог, поиск, PDP, раздел эфиров | `home`, `catalog`, `search`, `productDetail`, `liveList` | Выбор магазина. Показ дополнительно зависит от SDK policy и доступного места |
| Корзина, оформление, оплата, вход, профиль | `cart`, `checkout`, `payment`, `auth`, `profile` | `allowed: false`. SDK убирает окно и приостанавливает видео |
| Блокирующий sheet или диалог | Семантическая поверхность диалога | Сообщите запрет до презентации. После закрытия перечитайте маршрут и оставшиеся overlays |
| Собственный экран | `ShopStorySurface(rawValue:)` в Swift или `ShopStorySurface.custom(...)` в Dart | Стабильный идентификатор экрана. URL, ID пользователя и параметры маршрута в значение не входят |

Выберите один способ сообщать поверхности для плеера. Во Flutter с одним root Navigator можно применить `ShopStoryNavigatorObserver` и `surfaceForRoute`. Для вложенных стеков или declarative router один владелец состояния приложения вызывает `setCurrentSurface`. В ручной схеме дождитесь применения `allowed: false` до показа блокирующего окна.

Во Flutter оберните содержимое маршрутов в `ShopStorySurfaceScope(surface: ..., child: ...)`. Для `IndexedStack` передайте `active` из выбранной вкладки, даже если остальные вкладки смонтированы. Внутри builder корзины, sheet или диалога используйте `ShopStorySurfaceScope.blocking(surface: ..., child: ...)` с тем же плеером. Оставляйте блокировку активной до завершения анимации закрытия. Если роутер удерживает полностью перекрытый или уже закрытый popup, передайте ему `active: false`.

## Встройте список в навигацию магазина

Меню, баннер и CTA в сторис могут вести через существующий роутер на один и тот же экран «Эфиры». Закройте временное меню или сторис при переходе, чтобы Back вернул зрителя на исходную страницу. Встроенный список занимает выделенную область, поэтому app bar, таббар и навигация магазина остаются частью host.

### Native iOS

Метод ниже монтирует список в ограниченный контейнер UIKit. Его вызывает приложение после конфигурации SDK. Передайте контейнер, у которого уже есть собственный размер в layout.

StreamListContainer.swift

```swift
import ShopStoryPlayerSDK
import UIKit

@MainActor
func installStreamList(in container: UIView) -> ShopStoryStreamListView {
    let list = ShopStorySDK.shared.player.makeStreamListView()
    list.setActive(false)
    list.translatesAutoresizingMaskIntoConstraints = false
    container.addSubview(list)
    NSLayoutConstraint.activate([
        list.leadingAnchor.constraint(equalTo: container.leadingAnchor),
        list.trailingAnchor.constraint(equalTo: container.trailingAnchor),
        list.topAnchor.constraint(equalTo: container.topAnchor),
        list.bottomAnchor.constraint(equalTo: container.bottomAnchor)
    ])
    return list
}
```

Удерживайте возвращённый view. Вызывайте `setActive(true)`, пока маршрут списка выбран, и `setActive(false)`, когда его закрыла другая вкладка или страница магазина. При окончательном удалении маршрута вызовите `dispose()`. В SwiftUI тот же view можно смонтировать через `UIViewRepresentable` или использовать UIKit-контроллер контейнера через `UIViewControllerRepresentable`. Источник `active` — роутер, который знает, какой экран виден.

Для своего Back из встроенного анонса отслеживайте `onStreamCardVisibilityChanged` и при открытой карточке вызывайте `returnToStreamList()`. Когда виден сам список, Back обрабатывает роутер магазина.

### Flutter на iOS

Дайте виджету конечную ширину и высоту. Держите один список на Flutter engine. Ниже `selectedTab` и `routeIsVisible` поступают из вашего роутера.

streams_tab.dart

```dart
import 'package:flutter/material.dart';
import 'package:shopstory_player_flutter/shopstory_player_flutter.dart';

Widget storeTabs({
  required int selectedTab,
  required bool routeIsVisible,
  required Widget catalog,
  required Widget bottomNavigationBar,
}) {
  return Scaffold(
    appBar: AppBar(title: Text(selectedTab == 0 ? 'Каталог' : 'Эфиры')),
    bottomNavigationBar: bottomNavigationBar,
    body: IndexedStack(
      index: selectedTab,
      children: [
        catalog,
        ShopStoryStreamList(active: selectedTab == 1 && routeIsVisible),
      ],
    ),
  );
}
```

Не удаляйте виджет при обычной смене вкладки, если нужно сохранить фильтры. Новый mount начинает с фильтра «все». Для Back из анонса используйте обычный путь `Navigator.maybePop`, который учитывает `PopScope` списка. На экране самого списка Back должен возвращать управление вашему роутеру. `handleSystemBack()` в adapter предназначен для Android.

### Проверьте три состояния эфира

| Карточка | Что откроется | Что проверить |
| --- | --- | --- |
| Запланирован | Анонс с временем начала | На встроенном экране остаются панели магазина. Вернитесь в список по Back. Медиа не стартует до разрешённого live |
| В эфире | Полный live player | Дождитесь кадров и проверьте звук. Back из просмотра возвращает в список с прежним фильтром |
| Запись готова | Полный VOD player | Проверьте воспроизведение и сохранение фильтра после Back |

Список и категории загружаются из настроенного проекта ShopStory. Если запись ещё обрабатывается, оставьте пользователю рабочую навигацию. Прямое открытие по `streamId` в таком состоянии может вернуть `streamUnavailable` в Swift или `stream-unavailable` во Flutter. Модальный список имеет собственное закрытие и возвращает на исходный экран приложения.

### Возврат с конечного экрана

Действие «К списку эфиров» возвращает в тот же встроенный список с прежними фильтрами, если просмотр связан с этим списком и его контейнер всё ещё доступен. Для прямого входа по `streamId` или входа с PDP публичный API не принимает отдельный маршрут встроенного списка. Без доступного назначения Back плеера закрывает завершившийся просмотр и возвращает в приложение. Из приложения список можно открыть через свой роутер или явный вызов `openStreamList()` для модального режима.

### Переходы из встроенного списка

Back, Follow Me и закрытие сессии

```mermaid
---
config:
  theme: base
  fontFamily: Euclid Circular B, sans-serif
  themeVariables:
    fontSize: 18px
    primaryColor: '#f8f8fb'
    primaryTextColor: '#242329'
    primaryBorderColor: '#d8d7e0'
    lineColor: '#5c3dff'
    edgeLabelBackground: '#ffffff'
  flowchart:
    rankSpacing: 78
    nodeSpacing: 68
---
flowchart TB
    accTitle: Переходы из встроенного списка эфиров
    accDescr: Приложение управляет Back из списка и переходами магазина. Из анонса и полного плеера SDK возвращает во встроенный список. При блокировке Follow Me приостанавливается. Close завершает сессию.
    Store["Экран магазина"]
    List["Встроенный список<br/>Back приложения → экран магазина"]
    Scheduled["Анонс · панели магазина видимы<br/>Back анонса → список"]
    Player["Полный плеер · live или запись<br/>Back плеера → список"]
    PDP["PDP · Follow Me в той же сессии"]
    Blocked["Корзина / checkout / вход<br/>Окно скрыто · видео на паузе"]
    Restored["Возврат на разрешённую PDP<br/>Та же сессия"]
    Closed["Просмотр завершён"]

    Store -->|Меню, баннер или сторис| List
    List -->|Запланирован| Scheduled
    List -->|Live или запись| Player
    Player -->|Роутер открывает товар| PDP
    PDP -->|allowed: false| Blocked
    Blocked -->|Блокировки сняты| Restored
    PDP -->|"Крестик или close()"| Closed
```

Back из анонса или из просмотра, открытого списком, возвращает к прежним фильтрам. На PDP Follow Me продолжает ту же сессию, если окно включено и помещается. Тап по окну разворачивает плеер поверх PDP, Back следует политике этой PDP. SDK может восстановить окно и воспроизведение, когда разрешённый экран снова виден и блокировки сняты.

## Откройте эфир по ссылке

Приложение принимает Universal Link или deep link в своём роутере, проверяет допустимый домен и маршрут и передаёт SDK только `streamId` проекта. Дождитесь первого разрешённого видимого экрана. UIKit передаёт контроллер, уже находящийся в активном окне. Flutter сообщает поверхность из своего роутера и вызывает `await sdk.openStream(streamId: streamId)` с обработкой `PlatformException`. Рассматривайте результат открытия как подтверждение презентации. Проверку первого кадра выполняйте отдельно.

Для извлечения ID используйте `ShopStoryDeepLink`. Каноническая ссылка из кнопки «Поделиться» должна принадлежать вашему `applicationId`. Для собственного URL передайте `storeLink`, который возвращает ID только для известной схемы, домена и пути. Для push передайте уже проверенные приложением поля `applicationId` и `streamId`. Обрабатывайте пустой результат в роутере. [Swift 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>)

Проверьте холодный запуск и вход в запущенное приложение. Дубликаты доставки фильтрует приложение. При повторном открытии того же эфира SDK может использовать текущую сессию. Если SDK использовал текущую сессию записи, проверьте, что воспроизведение продолжается с прежней позиции. Приложение обрабатывает ошибки маршрута, занятый блокирующий экран и запись, которая ещё готовится.

## Откройте товарный эпизод записи

На PDP передайте `feedProductId` в `showProductVideo` или `ShopStoryProductDetailScope`. Если показ разрешён и для товара доступен эпизод, SDK показывает беззвучное превью по настроенному правилу первого появления. Тап открывает запись у товарного эпизода. Для явного открытия передайте в `open(entrypoint: ...)` полученный entrypoint целиком. Если для товара нет доступного видео, PDP остаётся без превью.

В записи начальная карточка, перемотка и обычное воспроизведение используют один таймлайн товаров. Если опубликованная метка записи и метка из каталога приходятся на одну позицию, используется опубликованная метка. Каталог заполняет пропуски. При адресном входе с PDP товар входа сохраняется до следующей метки после точки входа. На записи с несколькими товарами проверьте начальную карточку, соответствие видео нужному эпизоду и карточку после перемотки.

## Сохраните просмотр при переходе к товару

1. Подключите [обработчик открытия PDP](<https://docs.shopstory.live/docs/guide/mobile-sdk-cart>). Вызов навигации принимает роутер магазина.
2. После фактического открытия PDP сообщите `.productDetail` с допуском. На разрешённой PDP Follow Me продолжает ту же медиасессию, если включён и помещается.
3. Для автоматического измерения нижней панели с кнопкой корзины используйте Flutter `ShopStoryAvoidArea` или UIKit `avoidBottomBar(_:in:)`. SDK применяет оставшуюся область при показе, перетаскивании и восстановлении. Если окно с кнопками не помещается, SDK скрывает его и приостанавливает видео с сохранением медиасессии. При ручном размещении задайте размеры и отступы в `presentation` или запретите показ через `allowed: false`. [Flutter PDP](<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 и SwiftUI](<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>)
4. На корзине и checkout запретите показ. При возврате пересчитайте верхний экран. Разрешённый маршрут позволяет восстановить ранее игравшую сессию только после снятия всех препятствий. Ручная пауза и закрытие сохраняются.
5. На тестовом iPhone проверьте fullscreen → PDP → Follow Me → fullscreen, сворачивание к краю, раскрытие, закрытие и повторное открытие. Отдельно выполните вход в список при активном Follow Me и возврат с checkout по [чеклисту выпуска](<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>).

[Ролики с iPhone](<https://docs.shopstory.live/docs/guide/mobile-sdk#%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%81%D0%BA%D0%B8%D0%B9-%D1%81%D1%86%D0%B5%D0%BD%D0%B0%D1%80%D0%B8%D0%B9>) сняты с SDK `1.0.0-rc.1`. В обоих роликах видно, как Follow Me воспроизводит запись на карточке товара, скрывается в корзине и продолжает просмотр после возврата. Для проверки вашего layout используйте точный комплект и цену, корзину и роутер своего тестового приложения.
