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

# Корзина и условия товара в Mobile SDK

Начните с [работающего видео](<https://docs.shopstory.live/docs/guide/mobile-sdk#%D0%BD%D0%B0%D1%87%D0%B0%D1%82%D1%8C-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8E>). Приложение магазина сохраняет свою авторизацию, каталог, правила покупки и 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](<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>)

### Регистрация на native iOS

Функция принимает обработчики магазина. Удерживайте возвращённый adapter у владельца действующей корзины.

ShopStoryCart.swift

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

shopstory_cart.dart

```dart
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 с тестовой корзиной в памяти. [Запустите быстрый старт](<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>) с дополнительным флагом `--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 сохраняет измеренный нижний зазор. При возврате на другой экран действует его собственное размещение.

Поверхность до push и после Back во Flutter

```mermaid
---
config:
  theme: base
  fontFamily: Euclid Circular B, sans-serif
  themeVariables:
    actorBkg: '#f8f8fb'
    actorBorder: '#d8d7e0'
    actorTextColor: '#242329'
    actorLineColor: '#d8d7e0'
    signalColor: '#5c3dff'
    signalTextColor: '#4d4b55'
    noteBkgColor: '#f8f8fb'
    noteBorderColor: '#e7e6ec'
    noteTextColor: '#4d4b55'
  sequence:
    width: 120
    actorMargin: 28
    wrap: true
    mirrorActors: false
---
sequenceDiagram
    accTitle: Порядок событий маршрута во Flutter
    accDescr: Для корзины SDK запрещает показ до push. Для разрешённой PDP SDK получает поверхность после первого видимого кадра. После обратного перехода помощник вызывает restoreSurface. Приложение сообщает SDK видимый экран, затем screenClosed запускает чтение условий.
    participant Helper as Commerce route helper
    participant Router as Navigator
    participant App as Приложение
    participant SDK as ShopStory SDK
    alt Корзина · trackBlockingRoute
        Helper->>SDK: setCurrentSurface(allowed: false)
        Helper->>Router: push(route)
        Router-->>Helper: Первый видимый кадр
    else Разрешённая PDP · trackProductRoute
        Helper->>Router: push(route)
        Router-->>Helper: Первый видимый кадр
        Helper->>SDK: setCurrentSurface(allowed: true)
    end
    Helper->>SDK: screenOpened()
    Router-->>Helper: Back → route.completed
    Helper->>App: restoreSurface()
    App->>SDK: setCurrentSurface<br/>видимый экран
    Helper->>SDK: screenClosed()
    SDK->>SDK: Обновить условия товара
```

После завершения обратного перехода помощник вызывает `restoreSurface()`. В этой функции сообщите SDK фактически видимый экран. Затем `screenClosed()` запускает чтение условий. При отдельном изменении корзины вызовите `refreshCommerce()`.

open_store_cart.dart

```dart
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](<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>)

## Полный 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-данных](<https://docs.shopstory.live/docs/guide/custom-commerce-integrations>)

### Учитывайте поздние ответы

В полном 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](<https://docs.shopstory.live/docs/operations/troubleshooting#mobile-cart-recovery>)

Журнал сохраняет запрос до вызова Cart API. При ошибке сохранения запись в корзину не запускается. После перезапуска та же привязка восстанавливает исходный `operationId` и блокировку. Для разрешения SDK читает статус или допустимые свежие условия исходной корзины. Неопределённый исход остаётся открытым. Журнал защищён средствами iOS, исключён из backup и не сохраняет токены или аналитическую атрибуцию. Авторизация, чтение `getOperationStatus` и идемпотентность остаются у магазина и его Cart API.

Запись и проверка исхода в Commerce v1

```mermaid
---
config:
  theme: base
  fontFamily: Euclid Circular B, sans-serif
  themeVariables:
    actorBkg: '#f8f8fb'
    actorBorder: '#d8d7e0'
    actorTextColor: '#242329'
    actorLineColor: '#d8d7e0'
    signalColor: '#5c3dff'
    signalTextColor: '#4d4b55'
    noteBkgColor: '#f8f8fb'
    noteBorderColor: '#e7e6ec'
    noteTextColor: '#4d4b55'
  sequence:
    width: 120
    actorMargin: 28
    wrap: true
    messageMargin: 24
    mirrorActors: false
---
sequenceDiagram
    accTitle: Добавление в корзину и восстановление операции
    accDescr: Нативный SDK сохраняет запрос в журнале, если журнал включён. При неизвестном исходе покупатель может проверить исходную операцию с карточки товара. При подтверждении плеер показывает «В корзине». Окончательный отказ без записи снимает блокировку. Неизвестный исход сохраняет блокировку.
    participant Player as Плеер
    participant SDK as ShopStory SDK
    participant Adapter as Адаптер
    participant Cart as Cart API
    Player->>SDK: Купить · addDirectly
    Note over SDK: Журнал iOS сохраняет запрос и operationId, если включён
    SDK->>Adapter: startCommerceAction
    Adapter->>Cart: Добавить товар
    alt Запись подтверждена
        Cart-->>Adapter: Товар добавлен
        Adapter-->>SDK: added
        SDK-->>Player: В корзине
    else Подтверждён отказ до мутации
        Cart-->>Adapter: Записи нет
        Adapter-->>SDK: rejectedNoMutation
        SDK-->>Player: Показать отказ
    else Исход неизвестен
        alt Процесс работает
            Adapter-->>SDK: unknown
        else Перезапуск до ответа
            Note over SDK: Восстановить запрос из журнала
        end
        Player->>SDK: Покупатель проверяет исход с карточки
        opt В SDK ещё нет окончательного ответа
            SDK->>Adapter: getOperationStatus<br/>Исходный operationId
            Adapter->>Cart: Прочитать статус
            Cart-->>Adapter: Статус исходной операции
            Adapter-->>SDK: Результат проверки
        end
        alt Добавление подтверждено
            SDK-->>Player: В корзине
        else Окончательный отказ без записи
            SDK-->>Player: Показать отказ и снять блокировку
        else Исход всё ещё неизвестен
            SDK-->>Player: Сохранить блокировку
        end
    end
```

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

## Проверьте покупку в Release-сборке

1. Откройте видео без адаптера. Проверьте обычную PDP и отсутствие записи или ложного подтверждения.
2. Зарегистрируйте adapter до открытия плеера. Нажмите «Купить» один раз. Сверьте одну запись Cart API, SKU, исходный operation ID и изменение CTA.
3. Смоделируйте отказ и потерю ответа после dispatch. Проверьте состояние ошибки, сверку исходной операции и отсутствие второй записи при повторном открытии плеера.
4. Проверьте корзину и возврат из checkout. Раздельно выполните отмену, ошибку и успех оформления. Подтвердите правильную поверхность, паузу, актуальный CTA и сохранность исходного контекста покупки.
5. Для варианта с формой получения проверьте два результата. Форма может только изменить условия либо сама выполнить добавление. В последнем случае свежие данные показывают «В корзине» без второй записи.
6. Для варианта с журналом оборвите процесс после dispatch и до ответа. Откройте ту же корзину, затем другую. Проверьте исходный `operationId`, чтение статуса, изоляцию привязок и отсутствие второй записи. Отдельно проверьте отказ перед dispatch, если журнал недоступен.
7. Для Flutter watcher вызовите ошибку `refreshCommerce()` и повторно отправьте последнюю подтверждённую ревизию. Проверьте повторное чтение и отсутствие записи. Смените корзину и убедитесь, что старые события больше не вызывают refresh.

[Мобильная аналитика](<https://docs.shopstory.live/docs/guide/analytics-mobile>) описывает подтверждённое добавление и независимую проверку событий. Оплата и заказ фиксируются системой магазина.
