Перейти к основному содержимому
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

7.0.0 (Beta)

RuStore позволяет интегрировать платежи в мобильное приложение.

подсказка

  • Если не знаете с чего начать, прочтите инструкцию в сценариях использования.

  • Если вы переходите на Pay SDK с billingClient SDK, ознакомьтесь с инструкцией по переходу. Подробности о Pay SDK можно узнать тут.

Условия работы платежей​

  • Для приложения включена возможность покупок в RuStore Консоли.
  • Приложение не должно быть заблокировано в RuStore.
  • На устройстве пользователя установлена актуальная версия RuStore.
  • Пользователь авторизован в RuStore.
  • Пользователь не должен быть заблокирован в RuStore.

Подготовка к работе​

Для подключения пакета платежей к проекту выполните следующую команду.

flutter pub add flutter_rustore_billing

Инициализация​

Перед вызовом методов библиотеки необходимо выполнить её инициализацию. Сама инициализация происходит автоматически, но для работы SDK в вашем файле AndroidManifest.xml необходимо прописать consoleApplicationId.

build.gradle
<meta-data
    android:name="console_app_id_key"
    android:value="@string/CONSOLE_APPLICATION_ID" />

В strings.xml замените строку с вашим app_id.

build.gradle
<string name="CONSOLE_APPLICATION_ID">"your_app_id"</string>

CONSOLE_APPLICATION_ID — идентификатор приложения из консоли RuStore.

Где в RuStore Консоль отображаются идентификаторы приложений?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между apps/ и /versions. Например, для URL-адреса https://console.rustore.ru/apps/123456/versions ID приложения — 123456.

примечание

ApplicationId, указанный в build.gradle, должен совпадать с applicationId APK-файла, который вы публиковали в RuStore Консоль.

Важно
Подпись тестируемой сборки (например, debug) приложения должна совпадать с подписью сборки приложения, которая была загружена в консоль и прошла модерацию ранее (например, release)

Работа с SDK​

В SDK доступны 2 публичных интерактора:

  • PurchaseInteractor — интерактор, который позволяет работать с платежами и имеет несколько публичных методов:
    • getPurchase(purchaseId: PurchaseId): Task<Purchase> - позволяет получить информацию о покупке по её идентификатору;
    • getPurchases(): Task<List<Purchase>> - позволяет получить покупки пользователя. В списке возвращаются покупки в статусе CONFIRMED для непотребляемых товаров и PAID (статус, означающий холдирование средств и ожидающих подтверждения покупки со стороны разработчика);
    • getPurchaseAvailability(): Task<PurchaseAvailabilityResult> - возвращает результат доступности работы с платежами;
    • consumePurchase(purchaseId: PurchaseId, developerPayload: DeveloperPayload? = null) — позволяет совершить потребление покупки (только для потребляемых товаров).
  • ProductInteractor — интерактор, который позволяет работать с продуктами и имеет несколько публичных методов:
    • getProducts(productsId: List<ProductId>): Task<List<Product>>— позволяет получить информацию по продуктам по их ID.
      (Важно! Метод имеет ограничение в 1000 продуктов)
    • purchase(params: ProductPurchaseParams): Task<ProductPurchaseResult> — позволяет совершить покупку продукта

Также доступен RuStoreUtils — блок, включающий набор публичных методов:

  • isRuStoreInstalled — проверки наличия приложения RuStore на девайсе пользователя;
  • openRuStore — запускает мобильное приложение RuStore;
  • openRuStoreAuthorization — запускает мобильное приложение RuStore для авторизации, после успешной авторизации пользователя мобильное приложение RuStore автоматически закроется;
  • openRuStoreDownloadInstruction — открывает веб-страницу для скачивания мобильного приложения RuStore.

Проверка доступности работы с платежами​

Для проверки доступности платежей, вызовите метод getPurchaseAvailability. При его вызове проверяются следующие условия.

  • На устройстве пользователя установлена актуальная версия RuStore.
  • Приложение RuStore поддерживает функциональность платежей.
  • Пользователь авторизован в RuStore.
  • Пользователь и приложение не должны быть заблокированы в RuStore.
  • Для приложения включена возможность покупок в RuStore Консоли.

Если все указанные выше условия выполняются, возвращается PurchaseAvailabilityResponse.Available.В противном случае возвращается PurchaseAvailabilityResponse.Unavailable(val cause: Throwable), где cause — это ошибка о невыполненном условии.

Вызов метода getPurchaseAvailability
RuStorePayClient.instance.purchaseInteractor.getPurchaseAvailability().then((value) {
  if (value case Available _) {
    // Process purchases available
  } else if (value case Unavailable unavailable) {
    // Process purchases unavailable
  }
});

Получение списка продуктов​

Для получения продуктов, добавленных в ваше приложение через RuStore консоль, необходимо использовать метод getProducts.

RuStorePayClient.instance.productInteractor.getProducts(productIds).then((response) {
    for (final product in response.products) {
         print(product?.productId);
    }
}, onError: (err) {
    print("products err: $err");
   }
);

productIds: List<ProductId> — список идентификаторов продуктов (задаются при создании продукта в консоли разработчика). Список продуктов имеет ограничение в размере 1000 элементов.

Где в RuStore Консоль отображаются идентификаторы продуктов?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Выберите Монетизация в меню слева.
  3. Выберите тип товара: Подписки или Разовые покупки.
  4. Скопируйте идентификаторы нужных товаров.

Метод возвращает список продуктов. Ниже представлена модель продукта.

class Product {
   String productId;
   ProductType type;
   String amountLabel;
   int? price;
   String currency;
   String imageUrl;
   String title;
   String? description;
}
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • type — тип продукта. CONSUMABLE/NON-CONSUMABE (потребляемый/непотребляемый).
  • amountLabel — отформатированная цена покупки, включая валютный знак.
  • price — цена в минимальных единицах (в копейках).
  • currency — код валюты ISO 4217.
  • title — название продукта на языке language.
  • description — описание на языке language.
  • imageUrl — ссылка на картинку.

Структура ProductType.

enum ProductType {
  consumable,
  nonConsumable,
}
  • consumable — потребляемый (можно купить много раз, например: кристаллы в приложении);
  • nonConsumable — непотребляемый (можно купить один раз, например: отключение рекламы в приложении);

Покупка продукта​

Одностадийная оплата (без холдирования средств)

Вызов метода покупки продукта
RuStorePayClient.instance.productInteractor.purchaseOneStep(id).then((value) {
  // Process success
});

Двухстадийная оплата (с холдированием средств)

Вызов метода покупки продукта
RuStorePayClient.instance.productInteractor.purchaseTwoStep(id).then((value) {
  // Process success
});

Получение списка покупок​

Для получения списка покупок пользователя используйте метод getPurchases.

RuStorePayClient.instance.purchaseInteractor.getPurchases().then((purchase) {
  // Process success
});
class Purchase {
   String purchaseId;
   String productId;
   String invoiceId;
   String? orderId;
   PurchaseType purchaseType;
   ProductType productType;
   String description;
   String? purchaseTime;
   int price;
   String amountLabel;
   String currency;
   int quantity;
   PurchaseStatus status;
   String? subscriptionToken;
   String? developerPayload;
}
  • purchaseId — идентификатор покупки.
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • invoiceId — идентификатор счёта.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • purchaseType — тип покупки.
  • productType — тип продукта (потребляемый / непотребляемый / подписка): CONSUMABLE/NON-CONSUMABE/SUBSCRIPTION.
  • description — описание на языке language.
  • purchaseTime — время покупки.
  • price — цена в минимальных единицах (в копейках).
  • amountLable — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
  • purchaseState — состояние покупки:
    • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
    • CANCELLED — покупка отменена покупателем;
    • PROCESSING — запущена оплата;
    • REJECTED — покупка отклонена (например, ввиду недостатка средств)
    • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
    • CONFIRMED — покупка успешно оплачена;
    • REFUNDED — запрос на возврат средств за покупку совершён успешно;
    • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено.
  • DeveloperPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки.

Структура PurchaseType.

enum PurchaseType {
  oneStep,
  twoStep,
}

Получение сведений о покупке​

Для получения информации о покупке, используйте метод getPurchase. 
RuStorePayClient.instance.purchaseInteractor.getPurchase(purchaseId).then((purchase) {
  // Process success
});

Метод возвращает информацию о конкретной покупке в любом статусе. Ниже представлена модель покупки.

class Purchase {
   String purchaseId;
   String productId;
   String invoiceId;
   String? orderId;
   PurchaseType purchaseType;
   ProductType productType;
   String description;
   String? purchaseTime;
   int price;
   String amountLabel;
   String currency;
   int quantity;
   PurchaseStatus status;
   String? subscriptionToken;
   String? developerPayload;
}

Статусная модель покупки​

Статусная модель одностадийного платежа.



Статусная модель двухстадийного платежа.



Потребление (подтверждение) покупки​

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

Для списания средств с карты покупателя требуется подтверждение покупки. Для этого вы должны использовать метод confirmTwoStepPurchase.

RuStorePayClient.instance.purchaseInteractor.confirmTwoStepPurchase(purchaseId).then((value) {
  // Process success
});
  • id — идентификатор покупки.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки

Валидация покупок на сервере​

Если вам необходимо произвести валидацию успешной покупки на сервере RuStore, вы можете использовать subscriptionToken в ProductPurchaseResult.SuccessProductPurchaseResult, возвращаемой при успешной покупке продукта.

Также можно получить subscriptionToken в сущности Purchase. Сущность Purchase можно получить, используя метод getPurchases().

RuStorePayClient.instance.getPurchases().then((response) {
    for (final purchase in response.purchases) {
         print(purchase?.subscriptionToken);
    }
}, onError: (err) {
    print("purchases err: $err" );
   }
);

Отмена покупки​

Через SDK можно отменить только те покупки, которые были запущены по двухстадийному сценарию оплаты, т.е. с холдированием средств. Такие покупки после успешной оплаты будут находиться в статусе PurchaseStatus.paid. Отмена покупки фактически означает отмену холда средств.

RuStorePayClient.instance.purchaseInteractor.cancelTwoStepPurchase(id).then((value) {
  // Process success
});
  • id — идентификатор покупки.

Методы утилиты RuStoreFlutterUtils (публичные методы)​

Проверка наличия приложения RuStore на устройстве пользователя.

RuStorePayClient.instance.ruStoreUtils.isRuStoreInstalled().then((isInstalled) {

});

Метод возвращает логическое значение isInstalled.

Открытие веб-страницы для скачивания приложения RuStore.

RuStorePayClient.instance.ruStoreUtils.openRuStoreDownloadInstruction()

Запуск приложения RuStore

RuStorePayClient.instance.ruStoreUtils.openRuStore()

Запуск приложения RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закроется.

RuStorePayClient.instance.ruStoreUtils.openRuStoreAuthorization()

Обработка ошибок​

  • RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
  • RuStorePaymentCommonException — общая ошибка SDK;
  • RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
  • RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента её инициализации;
  • RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
  • RuStorePayInvalidConsoleAppId — не задан обязательный параметр сonsole_application_id для инициализации SDK;
  • RuStorePaySignatureException — неверная сигнатура ответа (возникает при попытке совершить мошеннические действия);
  • EmptyPaymentTokenException — ошибка получения платежного токена;
  • RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
  • RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK;
  • RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
  • RuStoreApplicationBannedException — приложение заблокировано в RuStore;
  • RuStoreUserBannedException — пользователь заблокирован в RuStore;
  • RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.