6.1.0 (Beta)

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

提示

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

Пример реализации

Ознакомьтесь с приложением-примером чтобы узнать, как правильно интегрировать SDK платежей.

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

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

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

Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
Скопируйте содержимое папки godot_example/android/plugins в папку your_project/android/plugins.
В пресете сборки Android в списке Плагины отметьте плагины Ru Store Godot Pay и Ru Store Godot Core.

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

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

<!-- Initializing sdk -->
<meta-data
    android:name="console_app_id_key"
    android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
<meta-data
    android:name="internal_config_key"
    android:value="@string/rustore_PayClientSettings_internalConfigKey" />

Оба значения должны располагаться внутри тега <application>.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.godot.game"
    android:versionCode="1"
    android:versionName="1.0"
    android:installLocation="auto" >
 
    <supports-screens
        android:smallScreens="true"
        android:normalScreens="true"
        android:largeScreens="true"
        android:xlargeScreens="true" />
 
    <uses-feature
        android:glEsVersion="0x00030000"
        android:required="true" />
 
    <application
        android:label="@string/godot_project_name_string"
        android:allowBackup="false"
        android:icon="@mipmap/icon"
        android:appCategory="game"
        android:isGame="true"
        android:hasFragileUserData="false"
        android:requestLegacyExternalStorage="false"
        tools:ignore="GoogleAppIndexingWarning" >
        <meta-data
            android:name="org.godotengine.editor.version"
            android:value="${godotEditorVersion}" />
        <activity
            android:name=".GodotApp"
            android:label="@string/godot_project_name_string"
            android:theme="@style/GodotAppSplashTheme"
            android:launchMode="singleInstancePerTask"
            android:excludeFromRecents="false"
            android:exported="true"
            android:screenOrientation="landscape"
            android:configChanges="orientation|keyboardHidden|screenSize|smallestScreenSize|density|keyboard|navigation|screenLayout|uiMode"
            android:resizeableActivity="false"
            tools:ignore="UnusedAttribute" >
 
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
 
        <!-- Initializing sdk -->
        <meta-data
            android:name="console_app_id_key"
            android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data
            android:name="internal_config_key"
            android:value="@string/rustore_PayClientSettings_internalConfigKey" />
    </application>
</manifest>

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

Где в RuStore Консоль отображаются идентификаторы приложений?

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

备注

Application Id приложения, указанный в Проект > Экспорт... > Android > Параметры > Уникальное Имя, должен совпадать с Application Id APK-файла, который вы публиковали в системе RuStore Консоль.

注意

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

注意

Не задавайте значения console_app_id_key и internal_config_key напрямую в манифесте. Строки должны располагаться в файле ресурсов, например: your_project/android/build/res/values/rustore_values.xml. При этом значение internal_config_key всегда должно быть godot.

Пример rustore_values.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="rustore_PayClientSettings_consoleApplicationId" translatable="false">198332</string>
    <string name="rustore_PayClientSettings_internalConfigKey" translatable="false">godot</string>
</resources>

Работа с SDK

Перед использованием всех методов плагина должен быть создан экземпляр объекта RuStoreGodotPayClient.

Создание инстанса RuStoreGodotPayClient
var _pay_client: RuStoreGodotPayClient = RuStoreGodotPayClient.get_instance()

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

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

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

Если все указанные выше условия выполняются, возвращается isAvailable == true. В противном случае возвращается isAvailable == false, где cause — это ошибка о невыполненном условии. Для проверки причины возвращения такого результата нужно проверить тип ошибки на RuStoreException (данные ошибки описаны в разделе Обработка ошибок).

Перед использованием метода необходимо единожды выполнить подписку на события:

on_get_purchases_availability_success;
on_get_purchases_availability_failure.

Подписка на события
func _ready():
    # Инициализация _pay_client
     
    _pay_client.on_get_purchase_availability_success.connect(_on_get_purchase_availability_success)
    _pay_client.on_get_purchase_availability_failure.connect(_on_get_purchase_availability_failure)
 
func _on_get_purchase_availability_success(result: RuStoreGetPurchaseAvailabilityResult):
    pass

Вызов метода get_purchase_availability
_pay_client.get_purchase_availability()

Проверка установки приложения RuStore

Чтобы проверить установлен ли на устройстве пользователя RuStore необходимо вызвать метод is_rustore_installed.

var is_rustore_installed: bool = _pay_client.is_rustore_installed()

true – RuStore установлен.
false – RuStore не установлен.

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

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

Перед использованием метода необходимо единожды выполнить подписку на события:

on_get_products_success;
on_get_products_failure.

Подписка на события
func _ready():
    # Инициализация _pay_client
     
    _pay_client.on_get_products_success.connect(_on_get_products_success)
    _pay_client.on_get_products_failure.connect(_on_get_products_failure)
 
func _on_get_products_success(products: Array[RuStorePayProduct]):
    pass
 
func _on_get_products_failure(error: RuStoreError):
    pass

Вызов метода get_products
var PRODUCT_IDS: Array[RuStorePayProductId] = [
    RuStorePayProductId.new("con_1"),
    RuStorePayProductId.new("non_con_1"),
]
 
_pay_client.get_products(PRODUCT_IDS)

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

Где в RuStore Консоль отображаются идентификаторы продуктов?

Перейдите на вкладку Приложения и выберите нужное приложение.
Выберите Монетизация в меню слева.
Выберите тип товара: Подписки или Разовые покупки.
Скопируйте идентификаторы нужных товаров.

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

class_name RuStorePayProduct extends Object
 
var productId: RuStorePayProductId = null
var type: ERuStorePayProductType.Item = 0
var amountLabel: RuStorePayAmountLabel = null
var price: RuStorePayPrice = null
var currency: RuStorePayCurrency = null
var imageUrl: RuStorePayUrl = null
var title: RuStorePayTitle = null
var description: RuStorePayDescription = null

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

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

Для вызова покупки продукта используйте метод purchase.

Перед использованием метода необходимо единожды выполнить подписку на события:

on_purchase_purchase_success;
on_purchase_purchase_failure.

Подписка на события
func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_product_success(_on_purchase_success)
    _pay_client.on_purchase_product_failure(_on_purchase_failure)
 
func _on_purchase_success(result: RuStorePayProductPurchaseResult):
    pass
   
func _on_purchase_failure(product_id: RuStorePayProductId, error: RuStoreError):
    pass

Вызов метода покупки продукта
var parameters = RuStorePayProductPurchaseParams.new(
      RuStoreProductId.new("product_id"),
        RuStoreQuantity.new(1),
      null,
      null);
 
_pay_client.purchase(parameters)

Структура параметров покупки.

Структура параметров покупки
class_name RuStorePayProductPurchaseParams extends Object
 
var productId: RuStorePayProductId = null
var quantity: RuStorePayQuantity = null
var orderId: RuStorePayOrderId = null
var developerPayload: RuStorePayDeveloperPayload = null
 
func _init(
    productId: RuStorePayProductId,
    quantity: RuStorePayQuantity = null,
    orderId: RuStorePayOrderId = null,
    developerPayload: RuStorePayDeveloperPayload = null
):
    self.productId = productId
    self.quantity = quantity
    self.orderId = orderId
    self.developerPayload = developerPayload

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки. Максимальная длина 250 символов.

Структура результата покупки.

Структура результата покупки
class_name RuStorePayProductPurchaseResult extends Object
 
class SuccessProductPurchaseResult extends RuStorePayProductPurchaseResult:
 
    var orderId: RuStorePayOrderId = null
    var purchaseId: RuStorePayPurchaseId = null
    var productId: RuStorePayProductId = null
    var invoiceId: RuStorePayInvoiceId = null
    var subscriptionToken: RuStorePaySubscriptionToken = null
 
class CancelProductPurchaseResult extends RuStorePayProductPurchaseResult:
 
    var purchaseId: RuStorePayPurchaseId = null
 
class FailureProductPurchaseResult extends RuStorePayProductPurchaseResult:
 
    var orderId: RuStorePayOrderId = null
    var purchaseId: RuStorePayPurchaseId = null
    var productId: RuStorePayProductId = null
    var invoiceId: RuStorePayInvoiceId = null
    var quantity: RuStorePayQuantity = null
    var subscriptionToken: RuStorePaySubscriptionToken = null
    var cause: RuStoreError = null

SuccessProductPurchaseResult — результат успешного завершения покупки цифрового товара.
FailureProductPurchaseResult — при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки.
CancelProductPurchaseResult — запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен.

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

Для получения информации о покупке, используйте метод get_purchase.

Подписка на события
func _ready:
    # Инициализация _pay_client
   
    _pay_client.on_get_purchase_success(_on_get_purchase_success)
    _pay_client.on_get_purchase_failure(_on_get_purchase_failure)
 
func _on_get_purchase_success(purchase: RuStorePayPurchase):
    pass
   
func _on_get_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass

Вызов метода получения информации о покупке пользователя
var purchase_id: RuStorePayPurchaseId = ...
 
_pay_client.get_purchase(purchase_id)

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

Структура с информацией о покупке
class_name RuStorePayPurchase extends Object
 
var purchaseId: RuStorePayPurchaseId = null
var productId: RuStorePayProductId = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var type: ERuStorePayPurchaseType = null
var description: RuStorePayDescription = null
var purchaseTime: RuStorePayTime = null
var price: RuStorePayPrice = null
var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var quantity: RuStorePayQuantity = null
var status: ERuStorePayPurchaseStatus = null
var subscriptionToken: RuStorePaySubscriptionToken = null
var developerPayload: RuStorePayDeveloperPayload = null

purchaseId — идентификатор покупки.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
type — тип покупки:
- APPLICATION
- NON_CONSUMABLE_PRODUCT
- CONSUMABLE_PRODUCT
- SUBSCRIPTION
description — описание на языке language
purchaseTime — время покупки:
price — цена в минимальных единицах (в копейках)
amountLable — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты
- CANCELLED — покупка отменена покупателем
- PROCESSING — запущена оплата
- REJECTED — покупка отклонена (например, ввиду недостатка средств)
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика
- CONFIRMED — покупка успешно оплачена
- REFUNDED — запрос на возврат средств за покупку совершён успешно
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
subscriptionToken — токен для валидации покупки на сервере

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

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

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Метод возвращает список покупок в статусах CONFIRMED (для непотребляемых товаров) и PAID (для потребляемых товаров). Ниже представлена модель покупки.

public class Purchase : BaseFields {
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType type { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}

purchaseId — идентификатор покупки.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
type — тип покупки:
- APPLICATION
- NON_CONSUMABLE_PRODUCT
- CONSUMABLE_PRODUCT
- SUBSCRIPTION
description — описание на языке language
purchaseTime — время покупки:
price — цена в минимальных единицах (в копейках)
amountLable — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты
- CANCELLED — покупка отменена покупателем
- PROCESSING — запущена оплата
- REJECTED — покупка отклонена (например, ввиду недостатка средств)
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика
- CONFIRMED — покупка успешно оплачена
- REFUNDED — запрос на возврат средств за покупку совершён успешно
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
subscriptionToken — токен для валидации покупки на сервере

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

RuStore содержит продукты следующих типов:

CONSUMABLE (потребляемый) — можно купить много раз, например кристаллы в приложении.
NON_CONSUMABLE (непотребляемый) — можно купить один раз, например отключение рекламы в приложении.

Подтверждения требуют только продукты типа CONSUMABLE, если они находятся в состоянии ERuStorePurchaseState.Item.PAID.

Для потребления (подтверждения) покупки используйте метод consume_purchase. Запрос на потребление (подтверждение) покупки должен сопровождаться выдачей товара. После вызова подтверждения покупка перейдёт в статус CONSUMED.

Перед использованием метода необходимо единожды выполнить подписку на события:

on_consume_purchase_success;
on_consume_purchase_failure.

Подписка на события
func _ready:
    # Инициализация _pay_client
   
    _pay_client.on_consume_purchase_success(_on_consume_purchase_success)
    _pay_client.on_consume_purchase_failure(_on_consume_purchase_failure)
 
func _on_consume_purchase_success(purchase_id: RuStorePayPurchaseId):
    pass
 
func _on_consume_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass

Вызов метода подтверждения
var id: RuStorePayPurchaseId = ...
var payload: RuStorePayDeveloperPayload = ...
 
_pay_client.consume_purchase(id, payload)

id — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки

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

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

Получение subscriptionToken из результата покупки
func _on_purchase_success(result: RuStorePayProductPurchaseResult):
    if result is RuStorePayProductPurchaseResult.SuccessProductPurchaseResult:
        yourApi.validate(result.subscriptionToken);

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

Получение subscriptionToken из результата покупки
func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
    for item in purchases:
        yourApi.validate(item.subscriptionToken);

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

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, от которой наследуются остальные ошибки.

6.1.0 (Beta)

Пример реализации​

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

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

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

Работа с SDK​

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

Проверка установки приложения RuStore​

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

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

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

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

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

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

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

Пример реализации

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

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

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

Работа с SDK

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

Проверка установки приложения RuStore

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

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

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

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

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

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

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