跳到主要内容

SDK Платежи in-app для Godot (версия 10.1.0)

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

提示

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

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

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

警告

Библиотеки плагинов в репозитории собраны для Godot Engine 4.2.1. Если вы используете другую версию Godot Engine, выполните шаги раздела Пересборка плагина.

  1. Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
  2. Скопируйте содержимое папки godot_example/android/plugins в папку your_project/android/plugins.
  3. В пресете сборки Android в списке Плагины отметьте плагины Ru Store Godot Pay и Ru Store Godot Core.
  4. Для Godot 4.2.2 и младше, в файле your_project/android/build/build.gradle добавьте секцию resolutionStrategy:
android {
    ...
}

configurations.all {
    resolutionStrategy {
        force 'androidx.core:core:1.9.0'
        force 'androidx.core:core-ktx:1.9.0'
        force 'androidx.lifecycle:lifecycle-runtime:2.6.2'
        force 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata-core:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-process:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata-core-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel-savedstate:2.6.2'
    }
}

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

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

Указание console_app_id и internal_config_key
<!-- Initializing sdk -->
<meta-data
    android:name="console_app_id_value"
    android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
<meta-data
    android:name="internal_config_key"
    android:value="@string/rustore_PayClientSettings_internalConfigKey" />

Оба значения должны располагаться внутри тега <application>. Также к тегу <application> добавьте аттрибут tools:replace="android:label".

AndroidManifest.xml
<?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" />
 
    <!-- Additional attribute tools:replace -->
    <application
        android:label="@string/godot_project_name_string"
		
        tools:replace="android:label"
        
        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_value"
            android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data
            android:name="internal_config_key"
            android:value="@string/rustore_PayClientSettings_internalConfigKey" />
    </application>
</manifest>

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

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

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

  • Подпись keystore должна совпадать с подписью, которой было подписано приложение, опубликованное в RuStore Консоль. Убедитесь, что используемый buildType (пр. debug) использует такую же подпись, что и опубликованное приложение (пр. release).

информация

В целях безопасности, SDK устанавливает android:usesCleartextTraffic="false" по умолчанию, чтобы предотвратить передачу данных по незащищённому HTTP и защитить от атак типа "Man-in-the-Middle". Если ваше приложение требует использования HTTP, вы можете изменить этот атрибут на true, но делайте это на свой страх и риск, так как это увеличивает шанс перехвата и подмены данных. Мы рекомендуем разрешать незащищённый трафик только в исключительных случаях и для доверенных доменов, предпочитая HTTPS для всех сетевых взаимодействий.

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

Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем приложении и возвращаться в ваше приложение.

Внимание

Допускаются только символы в кодировке ASCII. Формат должен соответствовать спецификации RFC-3986.

Для настройки deeplink в вашем приложении выполните два основных шага:

1. Измените код игровой активити.

  1. Откройте файл GodotApp.java расположенный по пути *your_project*/android/build/src/com/godot/game.
  2. Переопределите методы onCreate и onNewIntent для обработки входящих intent'ов, используя приведённый ниже код.
Пример GodotApp.java
package com.godot.game;

import android.content.Intent;
import android.os.Bundle;
import org.godotengine.godot.GodotActivity;
import ru.rustore.godot.pay.RuStoreGodotPay;

public class GodotApp extends GodotActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        setTheme(R.style.GodotAppMainTheme);
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            RuStoreGodotPay.proceedIntent(getIntent());
        }
    }

    @Override
    public void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        RuStoreGodotPay.proceedIntent(intent);
    }
}

Параметры метода proceedIntent:

  • Intent intent — интент, содержащий данные о платежной операции.
  • SdkTheme sdkTheme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT (необязательный параметр).
  • Long maxRetryTimeMs — максимальное время (в миллисекундах) для повторных попыток инициализации платёжного клиента, по умолчанию 5000 мс (необязательный параметр).

2. Обновите AndroidManifest.xml.

  1. В секцию <application>...</application> поместите тег meta-data с указанием ссылки на вашу Deeplink Scheme.
  2. Установите атрибут launchMode игровой активити в значение singleTop.
  3. Создайте activity-alias указав в атрибуте targetActivity класс игровой активити.
  4. Внутри activity-alias объявите intent-filter с указанием ссылки на вашу Deeplink Scheme.
AndroidManifest.xml
<?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"
        tools:replace="android:label"
        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}" />
		
        <meta-data
            android:name="console_app_id_value"
            android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data
            android:name="internal_config_key"
            android:value="@string/rustore_PayClientSettings_internalConfigKey" />
		
        <!-- 1. Deeplink scheme -->
        <meta-data
            android:name="sdk_pay_scheme_value"
            android:value="@string/rustore_PayClientSettings_deeplinkScheme" />

        <!-- 2. Game Activity launchMode="singleTop" -->
        <activity
            android:name=".GodotApp"
            android:label="@string/godot_project_name_string"
            android:theme="@style/GodotAppSplashTheme"
            android:launchMode="singleTop"
            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>
		
        <!-- 3. Аctivity-alias for Game Activity -->
        <activity-alias
            android:enabled="true"
            android:exported="true"
            android:name=".RuStoreDeeplink"
            android:targetActivity=".GodotApp" >

            <!-- 4. Deeplink intent-filter -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="@string/rustore_PayClientSettings_deeplinkScheme" />
            </intent-filter>
        </activity-alias>
    </application>
</manifest>

Значение deeplinkScheme должно располагаться в файле ресурсов, например: your_project/android/build/res/values/rustore_values.xml.

Внимание!

Не задавайте значение deeplinkScheme напрямую в манифесте.

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

Работа с SDK​

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

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

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

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

  • У компании подключена монетизация через консоль разработчика RuStore.
  • Приложение не должно быть заблокировано в RuStore.
  • Пользователь не должен быть заблокирован в RuStore.
Если все указанные выше условия выполняются, возвращается RuStorePayGetPurchaseAvailabilityResult.isAvailable == true.

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

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

  • 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: RuStorePayGetPurchaseAvailabilityResult):
    pass
	
func _on_get_purchase_availability_failure(error: RuStoreError):
    pass
Вызов метода get_purchase_availability
_pay_client.get_purchase_availability()

Проверка статуса авторизации пользователя​

Для проверки статуса авторизации пользователя, вызовите метод get_user_authorization_status. Результатом выполнения метода является значение перечисления ERuStorePayUserAuthorizationStatus.Item:

  • AUTHORIZED — пользователь авторизован в RuStore.
  • UNAUTHORIZED — пользователь неавторизован в RuStore. Данное значение также вернется если у пользователя нет установленного МП RuStore на девайсе.

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

  • on_get_user_authorization_status_success;
  • on_get_user_authorization_status_failure.
Подписка на события
func _ready():
    # Инициализация _pay_client
     
    _pay_client.on_get_user_authorization_status_success.connect(_on_get_user_authorization_status_success)
    _pay_client.on_get_user_authorization_status_failure.connect(_on_get_user_authorization_status_failure)
 
func _on_get_user_authorization_status_success(result: ERuStorePayUserAuthorizationStatus.Item):
    pass
 
func _on_get_user_authorization_status_failure(error: RuStoreError):
    pass
Вызов метода GetUserAuthorizationStatus
_pay_client.get_user_authorization_status()

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

Для получения продуктов, добавленных в ваше приложение через 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 Консоль отображаются идентификаторы продуктов?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Выберите Монетизация в меню слева.
  3. Выберите тип товара: Подписки или Разовые покупки.
  4. Скопируйте идентификаторы нужных товаров.

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

class_name RuStorePayProduct extends RefCounted
 
var productId: RuStorePayProductId = null
var type: ERuStorePayProductType.Item = 0
var amountLabel: RuStorePayAmountLabel = null
var price: RuStorePayPrice = null
var currency: RuStorePayCurrency = null
var title: RuStorePayTitle = null
var description: RuStorePayDescription = null
var imageUrl: RuStorePayUrl = null
var subscriptionInfo: RuStorePaySubscriptionInfo = null
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • type — тип продукта. CONSUMABLE/NON-CONSUMABLE/SUBSCRIPTION (потребляемый/непотребляемый/подписка).
  • amountLabel — отформатированная цена покупки, включая валютный знак.
  • price — цена в минимальных единицах (в копейках).
  • currency — код валюты ISO 4217.
  • title — название продукта на языке language.
  • description — описание на языке language.
  • imageUrl — ссылка на картинку.
  • subscriptionInfo — информация о подписке (будет не null, если тип продукта SUBSCRIPTION).
  • subscriptionInfo — информация о подписке (будет не null, если тип продукта SUBSCRIPTION).
Модель информации о подписке
class_name RuStorePaySubscriptionInfo extends RefCounted

var periods: Array[RuStorePaySubscriptionPeriod]
  • periods — cписок периодов подписки.
Модель периода подписки
class_name RuStorePaySubscriptionPeriod extends RefCounted

class RuStorePayTrialPeriod extends RuStorePaySubscriptionPeriod:
    var duration: String
    var currency: String
    var price: int

class RuStorePayPromoPeriod extends RuStorePaySubscriptionPeriod:
    var duration: String
    var currency: String
    var price: int

class RuStorePayMainPeriod extends RuStorePaySubscriptionPeriod:
    var duration: String
    var currency: String
    var price: int

class RuStorePayGracePeriod extends RuStorePaySubscriptionPeriod:
    var duration: String

class RuStorePayHoldPeriod extends RuStorePaySubscriptionPeriod:
    var duration: String
  • duration — длительность периода в формате ISO 8601.
  • currency — код валюты ISO 4217.
  • price — Цена в минимальных единицах валюты.

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

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

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

  • on_get_purchases_success;
  • on_get_purchases_failure.
Подписка на события
func _ready:
   # Инициализация _pay_client
   
   _pay_client.on_get_purchases_success.connect(_on_get_purchases_success)
   _pay_client.on_get_purchases_failure.connect(_on_get_purchases_failure)
 
func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
    pass
   
func _on_get_purchases_failure(error: RuStoreError):
    pass
Вызов метода получения списка покупок пользователя
# Инициализация _pay_client

# Вызов без фильтра
_pay_client.get_purchases()


# Вызов с фильтром
var product_type = ERuStorePayProductType.Item.CONSUMABLE_PRODUCT
var purchase_status = ERuStorePayPurchaseStatusFilter.Item.CONFIRMED

_pay_client.get_purchases(product_type, purchase_status)

Вызов с фильтром позволяет фильтровать покупки по типу товаров и статусу покупки:

product_type — типы товаров:

  • ERuStorePayProductType.Item.NON_CONSUMABLE_PRODUCT — непотребляемые товары.
  • ERuStorePayProductType.Item.CONSUMABLE_PRODUCT — потребляемые товары.
  • ERuStorePayProductType.Item.SUBSCRIPTION — подписки.

purchase_status — статусы покупок:

  • Для продуктов:

    • ERuStorePayPurchaseStatusFilter.Item.PAID — успешное холдирование средств, покупка ожидает подтверждения со стороны разработчика.
    • ERuStorePayPurchaseStatusFilter.Item.CONFIRMED — покупка подтверждена, средства списаны.

  • Для подписок:

    • ERuStorePayPurchaseStatusFilter.Item.ACTIVE — подписка активна.
    • ERuStorePayPurchaseStatusFilter.Item.PAUSED — подписка в Hold периоде (например, из-за недостатка средств на карте), продолжаются попытки списания в соответствии с настройками тарифа подписки.

По умолчанию фильтры выключены, если значения не заданы, метод вернёт все покупки пользователя в статусах PAID, CONFIRMED, ACTIVE и PAUSED, независимо от типа товара.

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

Для получения информации о покупке, используйте метод 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)

Типы покупок​

В SDK предусмотрен базовый класс RuStorePayPurchase, который объединяет общие поля всех типов покупок. На его основе созданы две реализации:

  • RuStorePayProductPurchase: для потребляемых и непотребляемых покупок.
  • RuStorePaySubscriptionPurchase: для подписок.

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

Базовый класс покупки
class_name RuStorePayPurchase extends RefCounted

var purchaseId: RuStorePayPurchaseId = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var description: RuStorePayDescription = null
var purchaseTime: RuStorePayTime = null
var price: RuStorePayPrice = null
var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var developerPayload: RuStorePayDeveloperPayload = null
var sandbox: bool = false
var _status = 0

Модель разовой покупки ProductPurchase​

Модель разовой покупки
class_name RuStorePayProductPurchase extends RuStorePayPurchase

var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var quantity: RuStorePayQuantity = null
var status: ERuStorePayProductPurchaseStatus.Item = 0

Унаследованные поля:

  • purchaseId — идентификатор покупки.
  • invoiceId — идентификатор счёта.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • PurchaseType — тип покупки:
    • ONE_PHASE - одностадийная покупка;
    • TWO_PHASE - двухстадийная покупка;
    • UNDEFINED - стадийность не определена.
  • description — описание на языке language.
  • purchaseTime — время покупки.
  • price — цена в минимальных единицах (в копейках).
  • amountLabel — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации

  • sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Уникальные поля:

  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • productType — тип продукта.
    • NON_CONSUMABLE_PRODUCT;
    • CONSUMABLE_PRODUCT.
  • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
  • status — состояние покупки:
    • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
    • CANCELLED — покупка отменена покупателем;
    • PROCESSING — запущена оплата;
    • REJECTED — покупка отклонена (например, ввиду недостатка средств);
    • CONFIRMED — покупка успешно оплачена;
    • REFUNDED — запрос на возврат средств за покупку совершён успешно. Деньги будут возвращены пользователю в течение 10 рабочих дней.;
    • REFUNDING — инициирован возврат, запрос отправлен в эквайер;
    • EXECUTING — покупка находится в процессе выполнения;
    • EXPIRED — истекло время на оплату покупки;
    • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
    • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.

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

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

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

Модель подписки SubscriptionPurchase​

class_name RuStorePaySubscriptionPurchase extends RuStorePayPurchase

var productId: RuStorePayProductId = null
var expirationDate: RuStorePayTime = null
var gracePeriodEnabled: bool = false
var status: ERuStorePaySubscriptionPurchaseStatus.Item = 0

Унаследованные поля:

  • purchaseId — идентификатор покупки.
  • invoiceId — идентификатор счёта.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • PurchaseType — тип покупки:
    • ONE_PHASE - одностадийная покупка;
    • TWO_PHASE - двухстадийная покупка;
    • UNDEFINED - стадийность не определена.
  • description — описание на языке language.
  • purchaseTime — время покупки.
  • price — цена в минимальных единицах (в копейках).
  • amountLabel — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации

  • sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Уникальные поля:

  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр). Идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • expirationDate — дата окончания действия подписки.
  • gracePeriodEnabled — флаг, указывающий, активен ли Grace-период для подписки.
  • status — состояние подписки:
    • INVOICE_CREATED — создан счет на оплату, подписка ожидает оплаты.
    • CANCELLED — счет на оплату подписки отменен.
    • EXPIRED — срок действия оплаты счета истек.
    • PROCESSING — первый платеж по подписке в обработке.
    • REJECTED — первый платеж по подписке отклонен. Подписка не оформлена.
    • ACTIVE — подписка активна.
    • PAUSED — подписка приостановлена из-за проблем с оплатой.
    • TERMINATED — закончились попытки списания по подписке (все были неуспешными). Подписка закрыта автоматически из-за проблем с оплатой.
    • CLOSED — подписка была отменена пользователем или разработчиком. Истек срок оплаченного периода, подписка закрыта.

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

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

Пояснения по работе с одностадийными и двухстадийными оплатами
  • При использовании одностадийного платежа покупка не требует подтверждения, денежные средства сразу списываются со счёта покупателя, а с разработчика удерживается комиссия. В таком случае, если требуется вернуть денежные средства клиенту (например, по какой-то причине нет возможности поставить продукт), возможен только возврат средств через RuStore Консоль, денежные средства возвращаются покупателю через несколько дней. Возвращается полная стоимость покупки, при этом удержанная комиссия разработчику не возмещается.
  • В случае использования двухстадийного платежа сначала производится холдирование средств на счете покупателя. Комиссия в этом случае не удерживается. После холдирования покупка требует подтверждения или отмены. Комиссия с разработчика удерживается при подтверждении покупки. Отмена покупки означает снятие холда - денежные средства мгновенно снова доступны покупателю.
Важно

Двухстадийная оплата доступна только для определенного набора способов оплаты (на текущий момент — только для карт). Технологии СБП не поддерживают двухстадийную оплату. Если выбран способ оплаты, который не поддерживает холдирование, то покупка будет запущена по сценарию с одной стадией.

Оплата с выбором типа покупки

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

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

  • on_purchase_success;
  • on_purchase_failure.
Подписка на события
func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_success(_on_purchase_success)
    _pay_client.on_purchase_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"), # productId
      null, # appUserEmail
      null, # appUserId
      null, # developerPayload
      null, # orderId
      RuStoreQuantity.new(1)); # quantity

var preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.ONE_STEP
var sdk_theme = ERuStorePaySdkTheme.Item.DARK

_pay_client.purchase(parameters, preferredPurchaseType, sdk_theme)
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются.
  • appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
    提示

    Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.

  • appUserEmail - это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.
  • preferredPurchaseType — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP).
  • sdk_theme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT.
Важно

Данный метод по умолчанию запускается по одностадийному сценарию оплаты (preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.ONE_STEP), т.е. без холдирования средств.

Для двухстадийной оплаты нужно указать preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.TWO_STEP. Двухстадийная оплата (т.е. оплата с холдированием средств) для данного метода не гарантирована и напрямую зависит от того, какой способ оплаты (карта, СПБ и др.) выбрал пользователь.

При запуске данного метода (с предпочитаемым preferredPurchaseType = twoStep), до тех пор пока пользователь не выберет способ оплаты, стадийность покупки будет UNDEFINED. Учитывайте данное поведение при обработке результатов отмены (ProductPurchaseCancelled) или ошибки (ProductPurchaseException) покупки.

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

信息

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

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

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

  • on_purchase_two_step_success;
  • on_purchase_two_step_failure.
Подписка на события
func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_two_step_success(_on_purchase_two_step_success)
    _pay_client.on_purchase_two_step_failure(_on_purchase_two_step_failure)
 
func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
    pass
   
func _on_purchase_two_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
    pass
Вызов метода покупки продукта
var parameters = RuStorePayProductPurchaseParams.new (
      RuStoreProductId.new("product_id"), # productId
      null, # appUserEmail
      null, # appUserId
      null, # developerPayload
      null, # orderId
      RuStoreQuantity.new(1)); # quantity
   );
var sdk_theme = ERuStorePaySdkTheme.Item.DARK

_pay_client.purchase_two_step(parameters, sdk_theme)

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

Структура параметров покупки
class_name RuStorePayProductPurchaseParams extends RefCounted

var productId: RuStorePayProductId = null
var appUserEmail: RuStorePayAppUserEmail = null
var appUserId: RuStorePayAppUserId = null
var developerPayload: RuStorePayDeveloperPayload = null
var orderId: RuStorePayOrderId = null
var quantity: RuStorePayQuantity = null

func _init(
   productId: RuStorePayProductId,
   appUserEmail: RuStorePayAppUserEmail = null,
   appUserId: RuStorePayAppUserId = null,
   developerPayload: RuStorePayDeveloperPayload = null,
   orderId: RuStorePayOrderId = null,
   quantity: RuStorePayQuantity = null
):
   self.productId = productId
   self.appUserEmail = appUserEmail
   self.appUserId = appUserId
   self.developerPayload = developerPayload
   self.orderId = orderId
   self.quantity = quantity
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются.
  • appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
    提示

    Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.

  • appUserEmail — это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.
  • sdkTheme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT.
Структура результата покупки
class_name RuStorePayProductPurchaseResult extends RefCounted

var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var sandbox: bool = false
  • invoiceId — идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
  • orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
  • productId — идентификатор приобретенного продукта, указанный при создании в консоли разработчика RuStore.
  • productType — тип продукта.
  • purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
  • purchaseType — тип покупки (ONE_STEP/TWO_STEP/UNDEFINED — одностадийная/двухстадийная/стадийность не определена).
  • quantity — количество товара.
  • sandbox — флаг, указывающий признак тестового платежа в песочнице. Если TRUE - покупка совершена в режиме тестирования.

Обработка ошибки оплаты​

Если в процессе оплаты возникает ошибка или пользователь отменяет покупку, выполнение метода оплаты (как с выбором типа покупки, так и двухстадийного метода) завершается с ошибкой:

  • ProductPurchaseException — ошибка покупки продукта.
  • ProductPurchaseCancelled — ошибка, вызванная отменой покупки продукта (пользователь закрыл платежную шторку) до получения результата покупки. В таком случае рекомендуется дополнительно проверить статус покупки методом получения информации о покупке.

Структура ошибки и отмены покупки:

  • ProductPurchaseResult — результат успешной оплаты цифрового товара (для одностадийной оплаты) или успешного холдирования средств (для двухстадийной оплаты).
class ProductPurchaseException extends RuStorePaymentException:
	
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var sandbox: bool = false
  • invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
  • orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
  • productId — идентификатор приобретённого продукта, указанный при создании в консоли разработчика RuStore.
  • productType - тип продукта (NON_CONSUMABLE_PRODUCT - непотребляемый товар, CONSUMABLE_PRODUCT - потребляемый товар, SUBSCRIPTION - подписка).
  • purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
  • purchaseType — тип покупки (ONE_STEP/TWO_STEP/UNDEFINED — одностадийная/двухстадийная/стадийность не определена).
  • quantity — количество товара, заданное при старте покупки.
  • sandbox — флаг, указывающий признак тестового платежа в песочнице. Если true — покупка совершена в режиме тестирования.

ProductPurchaseCancelled — отмена покупки цифрового товара. Платёжный диалог был закрыт до получения результата покупки, поэтому состояние покупки неизвестно. Рекомендуется запросить статус покупки отдельно методом получения информации о покупке.

class ProductPurchaseCancelled extends RuStorePaymentException:

var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
  • purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
  • purchaseType — тип покупки (ONE_STEP/TWO_STEP/UNDEFINED — одностадийная/двухстадийная/стадийность не определена).
  • productType — тип продукта (NON_CONSUMABLE_PRODUCT — непотребляемый товар, CONSUMABLE_PRODUCT — потребляемый товар, SUBSCRIPTION — подписка).
Пример обработки ошибок
func _on_any_purchase_failure(product_id: RuStorePayProductId, error: RuStoreError):
   if is_instance_of(error, RuStorePaymentException.ProductPurchaseCancelled):
      var cancelled_error = error as RuStorePaymentException.ProductPurchaseCancelled
      OS.alert(cancelled_error.purchaseId.value, error.name)
		
   elif is_instance_of(error, RuStorePaymentException.ProductPurchaseException):
      var exception_error = error as RuStorePaymentException.ProductPurchaseException
      OS.alert(exception_error.purchaseId.value, error.name)
		
   else:
      OS.alert(error.description, error.name)

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

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

Получение subscriptionToken из результата покупки
func _on_purchase_two_step_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);

Подтверждение покупки​

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

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

  • on_confirm_two_step_purchase_success;
  • on_confirm_two_step_purchase_failure.
Подписка на события
func _ready:
    # Инициализация _pay_client
   
    _pay_client.on_confirm_two_step_purchase_success(_on_confirm_two_step_purchase_success)
    _pay_client.on_confirm_two_step_purchase_failure(_on_confirm_two_step_purchase_failure)
 
func _on_confirm_two_step_purchase_success(purchase_id: RuStorePayPurchaseId):
    pass
 
func _on_confirm_two_step_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass
Вызов метода подтверждения
var id: RuStorePayPurchaseId = ...
var payload: RuStorePayDeveloperPayload = ...
 
_pay_client.confirm_two_step_purchase(id, payload)
  • id — идентификатор покупки.
  • payload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации

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

Для отмены покупки используйте метод cancel_two_step_purchase.

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

  • on_cancel_two_step_purchase_success;
  • on_cancel_two_step_purchase_failure.
Подписка на события
func _ready:
    # Инициализация _pay_client
  
    _pay_client.on_cancel_two_step_purchase_success(_on_cancel_two_step_purchase_success)
    _pay_client.on_cancel_two_step_purchase_failure(_on_cancel_two_step_purchase_failure)
	
func _on_cancel_two_step_purchase_success(purchase_id: RuStorePayPurchaseId):
    pass
  
func _on_cancel_two_step_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass
Вызов метода cancel_two_step_purchase
# Ваша реализация UI отмены покупки
func _on_cancel_two_step_purchase_pressed(purchaseId: RuStorePayPurchaseId):
    _pay_client.cancel_two_step_purchase(purchaseId)
purchaseId — идентификатор покупки

  • Обратный вызов (callback) on_cancel_two_step_purchase_success возвращает идентификатор покупки.
  • Обратный вызов (callback) on_cancel_two_step_purchase_failure возвращает идентификатор покупки типа String и объект RuStoreError с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

RuStoreUtils​

RuStoreUtils — это блок в нативном SDK, содержащий набор публичных методов, предназначенных для взаимодействия с приложением RuStore на устройстве пользователя.

Для доступа к методам блока в среде Godot используется синглтон класса RuStoreGodotCoreUtils.

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

Вызов метода is_rustore_installed
var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

var is_rustore_installed: Variant = _core_client.is_rustore_installed()

if is_rustore_installed == true:
    print("RuStore установлен на устройстве пользователя")
elif is_rustore_installed == false:
    print("RuStore не установлен на устройстве пользователя")
else:
    print("Состояние неизвестно (null)")

Метод open_rustore_download_instruction открывает веб-страницу для скачивания мобильного приложения RuStore.

Вызов метода open_rustore_download_instruction
var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.open_rustore_download_instruction();

Метод open_rustore запускает мобильное приложение RuStore. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

Вызов метода open_rustore
var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.Instance.open_rustore();

Метод open_rustore_authorization запускает мобильное приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закрывается. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

Вызов метода open_rustore_authorization
var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.Instance.open_rustore_authorization();

Список ошибок​

RuStoreError — базовый класс ошибки.

Класс RuStoreError
class_name RuStoreError extends RefCounted

var name: String = ""
var description: String = ""
  • name – имя ошибки.
  • description – описание ошибки.

RuStorePaymentException — базовый класс ошибки платёжного клиента.

class_name RuStorePaymentException extends RuStoreError

var cause: RuStoreError = null

...
  • cause – дополнительная информация об ошибке.

Унаследованные поля:

  • name – имя ошибки.
  • description – описание ошибки.

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK. В модели ошибки возвращается код ошибки (поле code), по которому можно определить причину ошибки. Таблица с кодами ошибок доступна в разделе коды ошибок.

Класс RuStorePaymentNetworkException
class_name RuStorePaymentException extends RuStoreError

...

class RuStorePaymentNetworkException extends RuStorePaymentException:
	
    var code = ""
    var id: String = ""
  • code — код ошибки.
  • id — идентификатор ошибки.

Унаследованные поля:

  • name – имя ошибки.
  • description – описание ошибки.
  • cause – дополнительная информация об ошибке.

Возможные ошибки

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