Переход с BillingClient SDK на Pay SDK: полный гайд для разработчиков
Рассказываем, что изменится, как подготовиться и провести миграцию без потерь для монетизации.
Команда RuStore продолжает развивать Pay SDK — новое платёжное решение, которое расширяет возможности монетизации и даёт больше гибкости при работе с покупками и подписками в сторе.
В рамках развития платформы мы постепенно завершаем поддержку BillingClient SDK: с 1 августа 2026 года он будет отключён. Мы заранее сообщаем об этом изменении, чтобы у разработчиков было достаточно времени спланировать переход: подготовить архитектуру, протестировать новую интеграцию и перенести текущие сценарии монетизации.
Мы рекомендуем использовать Pay SDK как в новых проектах, так и при обновлении существующих. При этом важно заранее оценить изменения и подготовить архитектуру, поскольку переход на новую платёжку — это не просто замена зависимости в проекте. В SDK обновлены подходы к инициализации, работе с deeplink, моделям статусов покупок, подтверждению платежей и логике подписок.
В документации RuStore уже доступен подробный гайд по миграции, а в этом материале разберём ключевые шаги перехода, основные отличия SDK и особенности работы с действующими подписками — чтобы провести обновление комфортно для пользователей и без потери выручки.
Что меняется при подключении Pay SDK
Pay SDK устроен иначе, и часть логики теперь выносится из кода в конфигурацию.
1. Подключение зависимости
Название SDK меняется (pay вместо billingclient), а список зависимостей становится короче — лишние параметры больше не нужны. По сути, теперь это более компактная и чистая интеграция.
2. Инициализация
В BillingClient SDK consoleApplicationId передавался в коде при создании клиента. В Pay SDK он указывается в AndroidManifest.xml. Туда же переносится и deeplink-схема. Это упрощает старт SDK: меньше ручной инициализации в коде, больше — декларативной настройки.
3. Работа с deeplink
Если раньше deeplink настраивался через фабрику клиента, то теперь схема прописывается в AndroidManifest, а для обработки используется отдельный IntentInteractor.
4. Проверка доступности платежей
Метод проверки меняется, а вместе с ним — типы ответов. Теперь возвращается PurchaseAvailabilityResult, а в случае ошибки приходит Throwable, а не RuStoreException. То есть обработка становится более универсальной.
5. Получение продуктов
В Pay SDK список продуктов можно запрашивать без авторизации пользователя. Плюс увеличен лимит: до 1000 товаров за один запрос вместо 100. Это упрощает загрузку каталога и снижает количество запросов.
Что изменилось в модели продукта
Структура Product обновлена: часть полей переименована или убрана, а для подписок появилось отдельное поле subscriptionInfo с детальной информацией о периодах — бесплатный (trial), стартовый (promo), основной (main), льготный (grace) и заморозка (hold). Если у вас есть кастомная логика отображения подписок, её нужно будет адаптировать под новую модель.
Всё это даёт более точную модель подписки и позволяет более гибко отображать информацию в интерфейсе.
6. Получение покупок
Метод получения покупок меняется, и появляется удобная фильтрация: по типу товара (разовые / подписки) и по статусу покупки.
Главное архитектурное изменение — теперь есть общий интерфейс Purchase и две реализации: ProductPurchase для разовых покупок, SubscriptionPurchase для подписок.
- ProductPurchase для разовых покупок,
- SubscriptionPurchase для подписок.
Это разделение делает модель чище, но потребует обновить обработку разных типов покупок в коде.
Статусы покупок
Статусная модель Pay SDK переработана:
- статусы стали более детализированными,
- логика различается для разовых покупок и подписок,
- для подписок появились отдельные состояния (например, ACTIVE, PAUSED, EXPIRED).
Если в проекте есть собственная логика маппинга статусов, её может потребоваться обновить для подписок, где появились дополнительные состояния. Логика разовых покупок не меняется.
Запуск покупки
Теперь используется универсальный метод purchase(), в котором можно выбрать тип оплаты:
- одностадийную (ONE_STEP),
- двухстадийную (TWO_STEP, с холдированием средств на карте пользователя)
Раньше стадийность была жёстко привязана к типу товара. Теперь разработчик может управлять этим параметром самостоятельно. Для гарантированной двухстадийной оплаты используется отдельный метод purchaseTwoStep().
Важно:
- двухстадийная схема доступна не для всех способов оплаты
- в отдельных сценариях набор доступных платёжных методов может отличаться
- для подписок используется только одностадийная оплата
Обработка ошибок
В Pay SDK:
- успешная покупка возвращается единым результатом,
- отмена и ошибки обрабатываются через OnFailureListener,
- добавлены отдельные типы исключений для отмены пользователем
Это немного меняет паттерн обработки результата, особенно если раньше логика была завязана на Success / Failure / Cancelled.
Серверная валидация
В BillingClient SDK для серверной проверки использовался purchaseToken. В Pay SDK для разовых покупок используется invoiceId, а для подписок — purchaseId. Если у вас настроена серверная проверка, этот блок нужно обновить отдельно.
Подтверждение и отмена двухстадийной покупки
Методы подтверждения и отмены изменились:
- подтверждение — confirmTwoStepPurchase(),
- отмена — cancelTwoStepPurchase().
Это актуально только для двухстадийной оплаты.
Продолжение статьи читайте в нашем блоге: https://www.rustore.ru/developer/blog/perekhod-s-billingclient-sdk-na-pay-sdk-polnyj-gajd