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

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

После первого запуска на iOS или Flutter на iOS подключите SDK к роутеру магазина. Выберите точку входа по задаче пользователя.

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

showProductVideo запрашивает и показывает видео на карточке. Полный плеер открывается по нажатию на товарное превью или окно прямого эфира. Как открыть товарный эпизод из своего интерфейса

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

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

Экран приложенияSurfaceЧто сообщить
Главная, каталог, поиск, PDP, раздел эфировhome, catalog, search, productDetail, liveListВыбор магазина. Показ дополнительно зависит от SDK policy и доступного места
Корзина, оформление, оплата, вход, профильcart, checkout, payment, auth, profileallowed: 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
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
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 и закрытие сессииПрокрутите схему по горизонтали
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 · Flutter reference

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

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

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

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

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

  1. Подключите обработчик открытия PDP. Вызов навигации принимает роутер магазина.
  2. После фактического открытия PDP сообщите .productDetail с допуском. На разрешённой PDP Follow Me продолжает ту же медиасессию, если включён и помещается.
  3. Для автоматического измерения нижней панели с кнопкой корзины используйте Flutter ShopStoryAvoidArea или UIKit avoidBottomBar(_:in:). SDK применяет оставшуюся область при показе, перетаскивании и восстановлении. Если окно с кнопками не помещается, SDK скрывает его и приостанавливает видео с сохранением медиасессии. При ручном размещении задайте размеры и отступы в presentation или запретите показ через allowed: false. Flutter PDP · UIKit и SwiftUI
  4. На корзине и checkout запретите показ. При возврате пересчитайте верхний экран. Разрешённый маршрут позволяет восстановить ранее игравшую сессию только после снятия всех препятствий. Ручная пауза и закрытие сохраняются.
  5. На тестовом iPhone проверьте fullscreen → PDP → Follow Me → fullscreen, сворачивание к краю, раскрытие, закрытие и повторное открытие. Отдельно выполните вход в список при активном Follow Me и возврат с checkout по чеклисту выпуска.

Ролики с iPhone сняты с SDK 1.0.0-rc.1. В обоих роликах видно, как Follow Me воспроизводит запись на карточке товара, скрывается в корзине и продолжает просмотр после возврата. Для проверки вашего layout используйте точный комплект и цену, корзину и роутер своего тестового приложения.