Корзина и условия товара в Mobile SDK
Начните с работающего видео. Приложение магазина сохраняет свою авторизацию, каталог, правила покупки и Cart API. SDK показывает действия, передаёт запросы приложению и отображает результат магазина.
| Сценарий | Что подключить |
|---|---|
| Просмотр без корзины | Конфигурация SDK. Адаптер корзины не нужен |
| Товары без вариантов и обязательной формы получения | ShopStorySimpleCommerceAdapter |
| Реальные варианты SKU, выбор магазина или доставки, восстановление незавершённых операций после перезапуска | Полный Commerce v1 |
Обе интеграции требуют явного выбора analytics и diagnostics до регистрации. Регистрируйте adapter после configure и до открытия первого плеера. Без адаптера «Купить» открывает PDP через зарегистрированный обработчик товара. Если обработчика PDP тоже нет, SDK скрывает кнопку. После снятия адаптера действуют те же правила. Уже отправленный запрос сохраняет исходный контекст корзины.
Простой адаптер
Используйте четыре обработчика приложения. По умолчанию структура товаров берётся из фида ShopStory. Если выбрано .api в Swift или ShopStoryCommerceCatalogSource.api в Dart, реализуйте также getProducts по контракту своего пакета.
| Callback | Действие и ответ |
|---|---|
getProductConditions | Прочитать текущие цену, доступность и inCart для запрошенного товара и текущей корзины. Вернуть ShopStorySimpleProductState. При сбое чтения сообщить ошибку |
addToCart | Проверить условия и добавить одну единицу в исходную корзину. Передать исходный operationId в Cart API, если сервис поддерживает идемпотентность |
openProduct | Разрешить ID в каталоге и открыть нативную PDP. Сохранить переданный контекст перехода для этой операции |
openCart | Открыть штатную корзину магазина для текущего контекста |
Сохраняйте строковые ID буквально, включая ведущие нули. Передавайте цену десятичной строкой с . и трёхбуквенной валютой, например amount: "1299.90", currency: "RUB". В ShopStoryCommercePrice используйте fromMinorUnits для целой суммы в минимальных денежных единицах, fromNum для числа в основных единицах и tryParse для строки с локальными разделителями. Укажите fractionDigits от 0 до 18. Для точных денежных расчётов используйте целые минимальные единицы. Фабрики отклоняют сумму, требующую округления, а tryParse также отклоняет неоднозначные строки. Неизвестную цену передавайте как nil / null, а сбой как ошибку чтения. Swift reference · Flutter reference
Регистрация на native iOS
Функция принимает обработчики магазина. Удерживайте возвращённый adapter у владельца действующей корзины.
import ShopStoryPlayerSDK
@MainActor
func installSimpleCart(
read: @escaping ShopStorySimpleCommerceAdapter.ConditionsHandler,
addOne: @escaping ShopStorySimpleCommerceAdapter.AddHandler,
product: @escaping ShopStorySimpleCommerceAdapter.ProductHandler,
cart: @escaping ShopStorySimpleCommerceAdapter.CartHandler
) throws -> ShopStorySimpleCommerceAdapter {
let adapter = ShopStorySimpleCommerceAdapter(
getProductConditions: read,
addToCart: addOne,
openProduct: product,
openCart: cart
)
try ShopStorySDK.shared.player.registerCommerce(adapter: adapter)
return adapter
}
По завершении addOne передайте .success(.added), .success(.rejectedNoMutation) или .success(.unknown) в completion. Обработчики и их completion имеют @MainActor-сигнатуры. Сетевой запрос выполняйте асинхронно, состояние UI обновляйте на главном акторе.
Регистрация во Flutter
import 'package:shopstory_player_flutter/shopstory_player_flutter.dart';
Future<void> installSimpleCart(ShopStorySimpleCommerceAdapter adapter) {
return ShopStoryPlayerFlutter.instance.registerCommerce(adapter: adapter);
}
В распакованном Flutter-примере lib/sample_simple_cart.dart содержит полный adapter с тестовой корзиной в памяти. Запустите быстрый старт с дополнительным флагом --dart-define=SHOPSTORY_QUICKSTART_SIMPLE_CART=true внутри той же команды ./run. Откройте эфир или запись с тестовым товаром и добавьте его в корзину. Сверьте, что добавилась одна единица и доступна корзина. Для своего приложения замените чтение и запись в памяти вызовами Cart API.
Прочитайте условия одним запросом
Если у вашего Cart API есть пакетный endpoint, в Swift создайте ShopStorySimpleCommerceAdapter(getProductsConditions: …), а во Flutter используйте ShopStorySimpleCommerceAdapter.batched(getProductsConditions: …). Верните словарь условий по точным ID из запроса. Отсутствующая строка означает недоступность покупки для этого товара. Валидные строки из того же ответа применяются. SDK заново читает условия после изменения корзины. С одиночным getProductConditions SDK выполняет до четырёх параллельных вызовов на одно чтение.
Сообщите об открытии и закрытии маршрута
Перед показом блокирующей корзины сообщите surface с allowed: false. После фактического открытия PDP или корзины вызовите events.screenOpened(). На закрытии сообщите видимую поверхность и вызовите events.screenClosed(). Если роутер не смог открыть экран, вызовите navigationFailed для запроса. В Dart дождитесь завершения возвращённого Future для каждого уведомления.
Во Flutter передайте фактический TransitionRoute в trackProductRoute для PDP или trackBlockingRoute для корзины. SDK подтверждает открытие после первого видимого кадра и ждёт route.completed до снятия запрета. restoreSurface сообщает экран, который стал видимым после закрытия. Избегайте дублирующих lifecycle-отчётов для того же перехода. Для declarative router и редиректов на авторизацию используйте отдельные события по фактическому состоянию маршрута. Переход на PDP или в корзину даёт ноль записей.
Если restoreSurface сообщает ту же видимую поверхность, которую ведёт ShopStorySurfaceScope, SDK сохраняет измеренный нижний зазор. При возврате на другой экран действует его собственное размещение.
restoreSurface(). В этой функции сообщите SDK фактически видимый экран. Затем screenClosed() запускает чтение условий. При отдельном изменении корзины вызовите refreshCommerce().import 'package:flutter/material.dart';
import 'package:shopstory_player_flutter/shopstory_player_flutter.dart';
Future<void> openStoreCart({
required ShopStoryPlayerFlutter player,
required ShopStoryCommerceEvents events,
required NavigatorState navigator,
required TransitionRoute<void> cartRoute,
required Future<void> Function() reportActualScreen,
}) {
return events.trackBlockingRoute<void>(
player: player,
navigator: navigator,
route: cartRoute,
surface: ShopStorySurface.cart,
restoreSurface: reportActualScreen,
);
}
Разберите результат добавления
| Ответ Cart API | Что вернуть SDK | Следующий шаг |
|---|---|---|
| Добавление подтверждено | added | Обновить условия товара и показать результат в обычной корзине |
| Отказ и магазин гарантирует отсутствие записи | rejectedNoMutation | Разрешить новую явную попытку после проверки условий |
| Таймаут или ответ потерян после dispatch | unknown | Сохранить исходные IDs и выяснить результат чтением. Повтор записи по одному таймауту создаёт риск дубля |
В простом адаптере свежее inCart: true по тому же товару и корзине может закрыть исходную незавершённую операцию. false, устаревшее состояние и ошибка чтения оставляют её открытой. При изменении цены, наличия или способа получения в той же корзине вызовите try sdk.player.refreshCommerce() на iOS или await sdk.refreshCommerce() во Flutter. При смене фактической корзины или аккаунта зарегистрируйте новую привязку, чтобы поздний ответ старой корзины не изменил новый CTA.
Если покупка началась в плеере A, а плеер B уже получил её как незавершённую, B обновляет кнопку по полным свежим условиям того же товара и корзины. Результат и подтверждение относятся к исходной операции A. Сверка выполняется чтением без повторной записи.
Подпишитесь на подтверждённые изменения корзины во Flutter
После регистрации вызовите watchConfirmedCartRevisions с basketId, lastConfirmedRevision, потоком changes и onError. Поток содержит (basketId: ..., revision: ...) после подтверждения Cart API. Для полного адаптера basketId совпадает с contextId. SDK объединяет ожидающие подтверждения в read-only refresh и пропускает чужие и устаревшие ревизии.
Если refreshCommerce() завершился ошибкой, onError получит её. Когда приложение готово повторить чтение, оно может снова отправить последнюю подтверждённую ревизию той же корзины. SDK ждёт нового события перед повтором. Дубли успешного или ещё выполняющегося чтения игнорируются.
Когда перестаёте отслеживать корзину, вызовите функцию отписки и дождитесь завершения её Future. SDK также завершает наблюдение при успешной замене привязки, смене контекста или очистке. Зарегистрируйте адаптер для новой корзины, затем подключите её поток. Сигнатура во Flutter
Полный Commerce v1
Используйте структуру товаров и SKU из фида ShopStory или своего API. Регистрируйте ровно один источник каталога на текущую commerce session. Для Flutter используйте registerCommerceAdapter(contextId:adapter:catalogSource:pendingOperations:) с именованными аргументами Dart. Для native iOS создайте ShopStoryCommerceSession(adapter:contextId:catalogSource:pendingOperations:) и присвойте её sdk.player.commerce. Сохраните session и adapter у объекта интеграции.
| Метод адаптера | Контракт магазина |
|---|---|
getProducts | Для источника .api вернуть структуру товара и реальные SKU для запрошенных ID |
getProductConditions | Вернуть актуальные условия для каждого запрошенного товара/SKU в переданном basket context |
startCommerceAction | addDirectly вызывает Cart API. chooseFulfilment и openMerchantFlow открывают экран магазина и передают lifecycle |
getOperationStatus | Прочитать исход уже отправленного запроса по его исходным IDs |
openProduct, openCart | Открыть штатные маршруты. Для контекста PDP в Swift используйте ShopStoryCommerceNavigationAdapter |
Передавайте priceStatus, showProduct, inCart и условия выбранного SKU. available: null допустим для chooseFulfilment до выбора получения. Для прямого добавления нужны available: true и непустой conditionsRef. Сами пользовательские формы и подтверждение их результата принадлежат магазину.
Используйте стабильный непрозрачный contextId корзины. Подробные типы и полный пример адаптера есть в ios/docs/COMMERCE-V1.md, flutter/doc/COMMERCE.md и flutter/example/lib/sample_commerce_store.dart в вашем комплекте. Источники commerce-данных
Учитывайте поздние ответы
В полном Commerce v1 на native iOS и Flutter iOS окончательный ответ по операции делает устаревшими сохранённые условия той же корзины и ответы на чтение, начатое раньше. Это действует и при замене commerce-сессии для той же корзины. Перед новым добавлением SDK должен получить актуальные условия. Cart API магазина должен возвращать состояние с учётом уже выполненных изменений или отклонять запись по устаревшему conditionsRef с гарантией отсутствия записи.
Если новый документ плеера восстановил покупку до получения подтверждения, SDK сохраняет поздний результат для исходной операции. Карточка может оставаться в состоянии неизвестного исхода. Покупатель может запустить проверку с карточки. SDK проверит статус по исходному operationId без повторного добавления.
Восстановите незавершённую покупку после перезапуска
На iOS полный Commerce v1 может вести локальный журнал. В Swift передайте pendingOperationDirectory как file URL в ShopStoryCommerceSession, во Flutter передайте абсолютный путь в первую registerCommerceAdapter. Используйте каталог Application Support своего приложения. Выберите один режим на время жизни сессии. В ручном режиме приложение сохраняет запрос до dispatch и передаёт через pendingOperations только исходные неразрешённые запросы.
При повторной регистрации Flutter используйте тот же каталог. SDK принимает эквивалентные пути к нему. Изменение каталога или режима восстановления отклоняется, пока сессия сохранена. Ошибки восстановления во Flutter
Журнал сохраняет запрос до вызова Cart API. При ошибке сохранения запись в корзину не запускается. После перезапуска та же привязка восстанавливает исходный operationId и блокировку. Для разрешения SDK читает статус или допустимые свежие условия исходной корзины. Неопределённый исход остаётся открытым. Журнал защищён средствами iOS, исключён из backup и не сохраняет токены или аналитическую атрибуцию. Авторизация, чтение getOperationStatus и идемпотентность остаются у магазина и его Cart API.
Проверьте покупку в Release-сборке
- Откройте видео без адаптера. Проверьте обычную PDP и отсутствие записи или ложного подтверждения.
- Зарегистрируйте adapter до открытия плеера. Нажмите «Купить» один раз. Сверьте одну запись Cart API, SKU, исходный operation ID и изменение CTA.
- Смоделируйте отказ и потерю ответа после dispatch. Проверьте состояние ошибки, сверку исходной операции и отсутствие второй записи при повторном открытии плеера.
- Проверьте корзину и возврат из checkout. Раздельно выполните отмену, ошибку и успех оформления. Подтвердите правильную поверхность, паузу, актуальный CTA и сохранность исходного контекста покупки.
- Для варианта с формой получения проверьте два результата. Форма может только изменить условия либо сама выполнить добавление. В последнем случае свежие данные показывают «В корзине» без второй записи.
- Для варианта с журналом оборвите процесс после dispatch и до ответа. Откройте ту же корзину, затем другую. Проверьте исходный
operationId, чтение статуса, изоляцию привязок и отсутствие второй записи. Отдельно проверьте отказ перед dispatch, если журнал недоступен. - Для Flutter watcher вызовите ошибку
refreshCommerce()и повторно отправьте последнюю подтверждённую ревизию. Проверьте повторное чтение и отсутствие записи. Смените корзину и убедитесь, что старые события больше не вызывают refresh.
Мобильная аналитика описывает подтверждённое добавление и независимую проверку событий. Оплата и заказ фиксируются системой магазина.